home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d12
/
cxl400.arc
/
CXL.DOC
next >
Wrap
Text File
|
1988-11-19
|
169KB
|
4,501 lines
C X L
The C Programmer's Extended Function Library
Version 4.0
July 27, 1988
by Mike Smedley
Copyright (c) 1987, 1988 All Rights Reserved
Reference Manual
1
TABLE OF CONTENTS
Page
Introduction..................................6
Features of the Library...................6
Registration Information..................7
How to Contact the Author.................7
Disclaimer................................8
Trademarks................................8
Tutorial......................................9
Windowing Functions (General).............9
Formatted Keyboard Input Functions.......10
Multi-Field Formatted Input Functions....13
Bar-Selection Menu Functions.............16
String Selection Functions...............20
Expanded Memory (EMS) Functions..........21
Mouse Functions..........................23
Global Variables.............................24
_cgasnow.................................24
_kbloop..................................24
_mouse...................................24
_onkey...................................24
_videoseg................................24
_werrno..................................24
_wesc....................................24
_whandle.................................24
_winp....................................24
_wmenu...................................25
_wrec....................................25
_wsel....................................25
_wtotal..................................25
Library Functions............................26
attrib...................................26
beep.....................................26
biosver..................................26
box_.....................................26
boxd.....................................27
capsoff..................................27
capson...................................27
clearkeys................................27
clockcal.................................27
clreol_..................................28
clrscrn..................................28
clrwin...................................28
cvaltype.................................28
delay_...................................29
disktoscrn...............................29
disktowin................................29
emsalloc.................................29
emsdealloc...............................30
emsexist.................................30
emsframe.................................30
emsfree..................................30
emsmap...................................31
2
emsread..................................31
emstotal.................................31
emsver...................................31
emswrite.................................32
expmem...................................32
extmem...................................32
fill_....................................32
filld....................................33
gameport.................................33
getchf...................................33
getns....................................34
getxch...................................34
gotoxy_..................................34
inputsf..................................34
kbstat...................................35
lcrlf....................................35
lprintc..................................35
lprintf..................................36
lprintns.................................36
lprints..................................36
lprintsb.................................36
lprintsu.................................36
machid...................................37
mathchip.................................37
mode.....................................37
msbpress.................................37
msbreles.................................38
mscursor.................................38
msgotoxy.................................38
mshbounds................................39
mshidecur................................39
msinit...................................39
msmotion.................................39
msshowcur................................40
msspeed..................................40
msstatus.................................40
msvbounds................................40
numflop..................................40
numoff...................................41
numon....................................41
numpar...................................41
numser...................................41
printc...................................41
printcd..................................42
prints...................................42
printsd..................................42
readchat.................................43
readcur..................................43
revattr..................................43
scrndump.................................43
scrntodisk...............................43
setattr..................................44
setcursz.................................44
setkbloop................................44
setlines.................................44
setonkey.................................45
sound_...................................45
3
spc......................................46
srestore.................................46
ssave....................................46
strblank.................................46
strbmatch................................46
strchg...................................47
strcode..................................47
strdel...................................47
strichg..................................48
stridel..................................48
striinc..................................48
strinc...................................49
strins...................................49
striocc..................................49
strleft..................................50
strltrim.................................50
strmatch.................................50
strmid...................................50
strocc...................................51
strright.................................51
strrol...................................51
strror...................................52
strsetsz.................................52
strshl...................................52
strshr...................................52
strtrim..................................53
struplow.................................53
sysdate..................................53
systime..................................54
tabstop..................................54
timer....................................54
touplow..................................54
videoinit................................55
vidtype..................................55
wactiv...................................55
waitkey..................................56
waitkeyt.................................56
waitvret.................................56
wblocked.................................56
wborder..................................57
wbox.....................................57
wcclear..................................57
wcenters.................................57
wchgattr.................................58
wclear...................................58
wclose...................................58
wcloseall................................58
wclreol..................................59
wclreos..................................59
wcopy....................................59
wdelline.................................59
wdupc....................................60
werrmsg..................................60
wfill....................................60
wfindrec.................................60
wgetc....................................61
wgetchf..................................61
4
wgetns...................................62
wgets....................................62
wgotoxy..................................62
whandle..................................63
whide....................................63
whline...................................63
winpdef..................................63
winpread.................................64
winputsf.................................64
winsline.................................65
wintodisk................................65
wisactiv.................................65
wmenudef.................................66
wmenuget.................................66
wmessage.................................67
wmove....................................67
wopen....................................68
wperror..................................68
wpgotoxy.................................68
wprintc..................................69
wprintf..................................69
wprints..................................69
wputc....................................70
wputns...................................70
wputs....................................70
wrestore.................................70
wrjusts..................................71
wsave....................................71
wsbounds.................................71
wscanf...................................72
wscroll..................................72
wsetesc..................................72
wsize....................................72
wsseldef.................................73
wsselget.................................73
wtextattr................................73
wtitle...................................74
wunhide..................................74
wvline...................................74
5
INTRODUCTION
The CXL library is intended to be a supplement to your compiler's
run-time library. It contains over 170 multi-purpose functions. The
main feature is the windowing system. There are many supporting
features as well. The library is available for several of today's
popular C compilers. These routines were written in highly-optimized C
code ensuring maximum program speed and minimum program size. This
release is an evaluation release containing everything you need to write
C programs using the small memory model. The libraries for the other
memory models are supplied when you register.
Features of the CXL Library.
- Multi-layered, overlapping windowing system
- Pop-up menus
- Pull-down menus
- Lotus-style menus
- Multi-field keyboard data entry
- Formatted keyboard input
- EGA 43-line and VGA 50-line modes
- DESQview compatibility
- Microsoft compatible mouse functions
- Lotus/Intel/Microsoft EMS memory functions
- Screen/window swapping to memory or disk
- Direct screen writing for fast screen writes
- Advanced string manipulation
- Keyboard event trapping
- Simple context sensitive help
- Pattern matching
- Data encryption
- Date and time functions
- Equipment detection
- Printing functions
- Sound functions
- and more!
6
Registration Information.
You are free to copy and distribute this library freely, however, if you
find this library of use to you, you are encouraged to register your
copy. The registration cost is only $25! Included in the registration
cost is:
- two 5.25-inch diskettes containing:
- the complete library source code! (100% native C code).
- libraries for the remaining memory models.
- royalty-free use of library functions.
- technical support.
- low-cost upgrades to future revisions.
- shipping and handling.
To register, print the registration form, REGISTER.DOC, by typing the
command "copy register.doc prn" from the DOS prompt and fill in the
requested information. Or you can use any piece of paper and include on
it your name, address, phone number, CompuServe/GEnie mail address, CXL
version, your compiler and its version, where you received CXL from, and
any comments. Non-U.S. orders add $5 for air mail. Send payment along
with registration information to:
Mike Smedley
P.O. Box 33603
San Antonio, TX 78265
How to Contact the Author.
U.S. Mail - see address above
Telephone - (512) 590-2910 (after 5 PM & weekends, not collect)
BIX - msmedley
CompuServe - 71331,2244
GEnie - M.SMEDLEY
Abbey Road BBS - (512) 590-6036 1200/2400/9600 8-N-1
Telstar BBS - (512) 822-8882 1200/2400 8-N-1
7
Disclaimer.
The author claims no responsibility for any damages caused by the use or
misuse of this library. This product is distributed "as is" with no
warranty expressed or implied. The author will not be responsible for
any losses incurred by the use of this product. The author reserves the
right to make modifications at any time. Prices are subject to change
without notice.
Trademarks.
BIX is a trademark of McGraw-Hill Inc.
CompuServe is a registered trademark of CompuServe Incorporated.
DESQview is a trademark of Quarterdeck Office Systems.
Epson is a registered trademark of Seiko Epson Corporation.
GEnie is a trademark of GE Information Services.
IBM is a registered trademark of International Business Machines.
LIM and EMS are trademarks of Lotus, Intel, and Microsoft Corps.
Lotus is a registered trademark of Lotus Development Corporation.
Microsoft is a registered trademark of Microsoft Corporation.
Turbo C is a registered trademark of Borland International.
Zortech is a trademark of Zortech Limited.
8
TUTORIAL
Windowing Functions (General).
CXL has a a powerful windowing system that can be very useful in an
application program. All windowing functions are prefixed with a 'w'.
The windowing is controlled by CXL's window manager which is called by
every windowing function. The window manager keeps track of which
window is active; each window's position, cursor location, attributes,
etc.; how many windows are open; and other information.
All windowing functions set the _werrno global variable before
returning. The literal value of this variable can be viewed by calling
the werrmsg() function. This feature is useful for debugging programs
that use the windowing functions.
Windows can have a border or be borderless. Borderless windows have a
greater effective region of which to work with. Window borders can be a
variety of styles.
Windows may also have titles. If the window has a border, the title
will be displayed on the top border. The window title can also be
used to name a window allowing easier identification.
You may open as many windows as memory permits. Once a window is
opened, it immediately becomes the active window. CXL's windowing
functions can only be performed on the active window. If you want to
perform a function on a inactive window, you must activate it first.
Once you have a window opened, you may perform a variety of tasks in it
including displaying output, accepting input, resizing, changing colors,
moving, changing border style, and more. See the supplied CXLDEMO.C
program for a complete example of how to use the windowing system.
Example:
WINDOW w1,w2; /* window handles */
/* open 1st window */
w1=wopen(0,0,10,40,0,LCYAN|_BLUE,LCYAN|_BLUE);
if(!w1) error_routine(); /* check for error */
wputs("Hello, "); /* display string */
/* open 2nd window */
w2=wopen(7,20,18,60,2,LRED|_MAGENTA,LRED|_MAGENTA);
if(!w2) error_routine(); /* check for error */
wputs("Hello, "); /* display string */
wactiv(w1); /* activate 1st window */
wputs("there"); /* display string */
wactiv(w2); /* activate 2nd window */
wputs("there"); /* display string */
wclose(); /* close 2nd window */
wclose(); /* close 1st window */
9
Formatted Keyboard Input Functions.
The inputsf() and winputsf() functions in CXL accept keyboard input
through the use of CXL's own input format strings. These format strings
are not the same as what scanf() uses. They have the ability to
restrict and convert input for each character received from the
keyboard. They also allow for custom prompts between each character
input. The format control characters can be in any order in the string,
but all letters must be in the case shown here. Invalid control
characters will cause the function to return an error and the receiving
string will be empty. Spaces can be used to improve readability of the
format string. If the Escape key is not disabled, when pressed it will
return an error code and the receiving string will be empty. Valid
format control characters are:
!.......! - start and end exclamation points, any letters between
them are format command toggles. The valid format
command toggles are:
- - decreases text attribute, works with
winputsf() only
+ - increases text attribute, works with
winputsf() only
C - toggles copying of display (quoted) characters
to the receiving string. (default is off)
E - toggles Escape key checking off/on. When off,
if the Escape key is pressed, the function
returns an error code and the string will be
null. The default for inputsf() is on. For
winputsf(), the default is the value of the
global variable _wesc upon calling.
L - toggles lower-case conversion. When on, the
case of input letters will be forced to lower
case. (default is off)
M - toggles mixed-case conversion. When on, the
case of input letters will be forced to
upper-case for the first letter of each word
and lower-case for the remaining letters.
(default is off)
P - toggles password mode. When on, input
characters will be echoed to the screen as
spaces. (default is off)
R - toggles return key checking. When off, the
carriage return key will be ignored until the
end of the format string. (default is on)
U - toggles upper-case conversion. When on, the
case of input letters will be forced to
10
upper-case. (default is off)
'.......' - start and end quotes, any characters between them will
.OR. be displayed as text. If the 'C' command toggle is
\".....\" on, the characters will also be copied to the
receiving string.
# - accept numeric character '0' thru '9'.
9 - accept numeric character '0' thru '9', '.', '-', and '+'.
? - accept any character.
* - accept any printable character.
A - accept alpha character 'A' thru 'Z', 'a' thru 'z', and
space.
D - accept character associated with a numeric date '0' thru
'9', '-', and '/'.
L - accept alpha character 'A' thru 'Z', 'a' thru 'z', and
space. Input characters will be converted to lower case.
M - accept alpha character 'A' thru 'Z', 'a' thru 'z', and
space input character will be converted to mixed case.
P - accept alphanumeric password character 'A' thru 'Z',
'a' thru 'z', '0' thru '9', and space.
T - accept character associated with a telephone number
'0' thru '9', '(', ')', '-', and space.
U - accept alpha character 'A' thru 'Z', 'a' thru 'z', and
space input character will be converted to upper case.
X - accept alphanumeric character 'A' thru 'Z', 'a' thru 'z',
'0' thru '9', and space.
Y - accept a yes/no character 'Y', 'y', 'N', and 'n'.
<.......> - set inclusion. Accept a character from valid list of
characters between angle brackets.
[.......] - set exclusion. Accept a character which cannot be
present in between the square brackets.
Examples:
inputsf(str,"'Enter name: ' !UR! XXXXX !R! XXXXXXXXXX");
Prompts for name, inputs string from keyboard converting characters to
upper case as it goes, allows up to 15 alphanumeric characters as input.
The return key is disabled until at least 5 characters have been
entered. Characters will be copied to str. This space must already be
allocated!
inputsf(str,"!R! 'Enter phone: '!C! '(' ### ') ' ### '-' ####");
Prompts for a full phone number including area code, allows only digit
characters and displays format punctuation as it goes. The entire field
must be filled before return can be pressed. All of the characters
except the prompt will be copied to the receiving string. The input
string will be copied to str, which must have already been allocated.
11
inputsf(str,"!R!'Enter SSAN: '<0123456>##'-'##'-'####");
Prompts for a Social Security number. Will not allow return to be
pressed until all digits have been entered. The first digit of the SSAN
must be 0 - 6. Dashes will be displayed as you are typing in the data,
but will not be contained in the receiving string str.
inputsf(str,"!R!'Enter DOB (MM/DD/YY): '<01>#'/'<0123>#'/'##");
Prompts for Date of Birth. Allows only valid digits for the input date.
Prevents the return key from working until all digits have been typed
in.
12
Multi-Field Formatted Input Functions.
Two functions are needed to process multi-field keyboard input from
windows: winpdef(), and winpread(). The winpdef() function defines
your input field and is called for each input field to be defined. The
winpread() function processes all defined fields. The formatted input
capabilities are much like those of the inputsf() and winputsf()
functions. The major difference is that with the winpdef()/winpread()
combination, you can edit back and forth between fields before finally
accepting the input.
For every input field you want to define, you must call winpdef(). This
will allocate memory to hold the input record information. The first two
parameters, wrow and wcol, specify where in the active window the field
will be loaded. The next parameter, str, is the address of the string
buffer to receive the input data.
The next parameter, format, is the input field format string. It
controls how each character is input and how large the input field will
be. It consists of 1 or more format characters, and may have displayed
text in between any of the format control characters. You may use
spaces in between the format control characters for readability. Valid
format control characters are listed in the "Formatted Keyboard Input
Functions" section. The case of the format control characters must be
as shown. Format strings for winpdef() are just like those of inputsf()
and winputsf() except there are no command toggles. If you make a syntax
error in the format string, winpdef() will return W_INVFORMT to notify
you of the mistake.
The next parameter in the winpdef() function is fconv. These are
similar to the command toggles of inputsf() and winputsf() except that
the fconv character applies conversion to the whole field. Valid fconv
characters are:
0 - apply no conversion
'L' - convert letters to lower case
'M' - convert letters to mixed upper & lower case
'P' - password field (do not echo characters)
'U' - convert letters to upper case
The next parameter in the winpdef() function is fattr. This is the text
attribute of the screen field. After the fattr parameter comes the
update parameter. This parameter allows you to specify if the input
field is going to create new data or update old data. If the update
parameter is 0, then the input field will be used for entering new data.
If the update parameter is non-zero, then the input field will be used
to update the old data contained in the str parameter. If you do choose
to update, then the length of the str string must be the same as the
length of the input field defined in the format string. If the two
lengths don't match, then winpdef() will return W_LENFORMT.
The last parameter in the winpdef() function is validate. This
parameter is the address of an optional user validation/modification
function. If no validation function is to be used, then specify NULL.
Your user validation/modification function must be declared like:
13
int func(char *str);
where str is the address of the input field that will be passed to it.
Once your user function has the address of the input field, you can
validate and/or modify the input field. Your function can also display
an error message, sound a bell, or just about anything. When your
function is done, it must return 0 for no error.
Once you have defined all input fields with winpdef(), you call
winpread() to process them. The user is allowed to move around and edit
all of the fields. The input fields are validated on the fly and after
entering the last field. Valid editing keys are:
LeftArrow - moves cursor left a position.
RightArrow - moves cursor right a position.
UpArrow - moves cursor to the previous field up.
DownArrow - moves cursor to the next field down.
Ctrl-LeftArrow - moves cursor to previous word left.
Ctrl-RightArrow - moves cursor to next word right.
Tab - moves cursor to the next field right.
Shift-Tab - moves cursor to the previous field left.
Enter - if the cursor is in the last field on the
screen, it will process all fields. Otherwise
it will skip to the next field.
Ctrl-Enter - processes all fields, wherever cursor may be
Home - moves cursor to first position of field.
End - moves cursor to last position of field.
Ctrl-Home - moves cursor to the first position of the
first field on the screen.
Ctrl-End - moves cursor to the last position of the last
field on the screen.
Ins - inserts a space at cursor location. All text
to the right of the cursor will be shifted
right. The end character will be dropped.
Del - deletes character at the cursor location. All
text to the right of the cursor will be
shifted left and a space will be inserted at
the end of the field.
BackSpace - deletes a character to the left.
Ctrl-BackSpace - deletes a word to the left. Text following
the word will be shifted left.
Ctrl-T - deletes a word to the right. Text following
the word will be shifted left.
Ctrl-U - deletes all characters from current cursor
postion to end of field.
Ctrl-Y - deletes all characters in all fields from
current cursor position to end of last field.
Esc - if enabled, cancels input and returns a
W_ESCPRESS value. Escape checking can be
enabled or disabled by calling the wsetesc()
function before winpread() is called.
After the winpread() function is called, all fields defined with
winpdef() will be cleared. The receiving strings of all defined fields
will now contain the data entered. If Escape checking was on and the
Esc key was pressed, then all receiving strings will contain the values
14
they held before winpread() was called and W_ESCPRESS will be returned.
15
Bar-Selection Menu Functions.
Two functions are needed to use CXL's bar-selection menus: wmenudef(),
and wmenuget(). These two functions can be used as part of a pull-down,
pop-up, Lotus-style, or any other bar-selection menu system. The
wmenudef() function defines a menu record in memory and displays the
menu option on the screen. The wmenuget() function processes the user's
selection and deallocates the defined menu records.
The wmenudef() function accepts 7 parameters. The first two parameters,
wrow and wcol, indicate where in the active window the menu option will
be displayed. The 3rd parameter, attr, is the text attribute of the
menu option. The 4th parameter, str, is the address of the string
containing the menu option. The 5th parameter, tagchar, is used for
identification of the menu option. The tag character may be any ASCII
character (value 0 - 255). Lower case tag characters will automatically
be converted to upper case. The 6th parameter, tagattr, is the
attribute of the tag character (if the tag character is present in the
menu option). The last parameter, desc, is the address of a text
description of the menu option. This is only used if you plan to use
Lotus-sytle menus, otherwise specify NULL.
When all menu options have been defined, you will call the wmenuget()
function. The first argument to wmenuget() is the attribute of the
selection bar. The second argument is the tag character of where you
want the selection bar to initially be located. If an undefined tag
character is used, then the initial position of the selection bar will
default to the upper-leftmost option. The third argument of wmenuget()
is the pulldown parameter. This is used for a pull-down menu system.
If a pull-down menu system is not being used, then the pulldown
parameter should be specified as zero.
If you are using pull-down menus, then the pulldown parameter may have
one of four values. PDMAIN is used to signify that the menu you have
just defined is to be the main menu (usually the horizontal bar across
the top) of a pull-down menu system. PDMENU is used to signify that the
menu you have just defined is one of the pull-down menus from the main
menu. The other two values that the pulldown parameter can have are
used for movement between pull-down menus. PDPREV is used to signify
that the menu you have just defined is the main menu and you wish to
automatically select the option previous to the specified taginit.
PDNEXT is used to signify that the menu you have just defined is the
main menu and you wish to automatically select the next option after the
specified taginit.
A mouse can be used for motion/selection of menu options. The mouse
must first be initialized with a call to msinit(). It is also
recommended that you adjust the mouse sensitivity by calling
msspeed(128,32) - the recommended settings for pull-down menus.
Keyboard movement/selection keys that can be used during the wmenuget()
function are:
LeftArrow - moves selection bar to previous option left. If
inside a pull-down menu, pressing this will cause
16
wmenuget() to return PDPREV.
RightArrow - moves selection bar to next option right. If inside a
pull-down menu, pressing this will cause wmenuget() to
return PDNEXT.
UpArrow - moves selection bar to previous option up.
DownArrow - moves selection bar to next option down. If pull-down
menus are being used and you are currently in the main
menu, then the option that the selection bar is on is
selected.
Tab - moves selection bar to next option right.
Shift-Tab - moves selection bar to previous option left.
Enter - selects the option that the selection bar is on.
Pressing the left mouse button will have the same
effect.
Home - moves selection bar to upper left option.
End - moves selection bar to lower right option.
Esc - if enabled, cancels input and returns a zero. Escape
checking can be enabled or disabled by using the
wsetesc() function before wmenuget() is called. If
inside a pull-down menu, pressing this will cause
wmenuget() to return PDMAIN. Pressing the right mouse
button will have the same effect.
When an option is selected, it's tag character will be returned by
wmenuget(). The tag character will be in the same case as when defined.
If the Esc key was pressed and Escape checking was on, a zero will be
returned and the global variable _werrno will be set to W_ESCPRESS. If
any other error occurred, the return value will be zero and the global
variable _werrno will be set to an error code (see CXLWIN.H). Once a
selection is made, the wmenuget() function automatically clears all menu
options defined by wmenudef().
If you are using wmenuget() to process a pull-down menu (PDMENU), and
the LeftArrow or RightArrow key is pressed, then wmenuget() will return
PDPREV or PDNEXT, respectively. This allows you to input these return
values back into the main menu's wmenuget() pulldown parameter to
automatically select the previous or next pull-down window from the
current pull-down window. The Escape checking status will be ignored
while inside a pull-down menu. Instead, if in a pull-down menu
(PDMENU), and the Esc key is pressed, wmenuget() will return PDMAIN,
which allows you to reinput that value back into the main menu's
wmenuget() pulldown parameter. If your pull-down system needs
3rd-level menus, they should be defined as pop-up menus (pulldown = 0).
Example for a Vertical Pop-Up Menu:
int selection;
/* open the window */
wopen(5,10,20,50,4,LMAGENTA|_RED,LMAGENTA|_RED);
/* define the menu */
wmenudef(2,2,LGREEN|_RED,"Add record",'A',WHITE|_RED,NULL);
wmenudef(4,2,LGREEN|_RED,"Delete record",'D',WHITE|_RED,NULL);
wmenudef(6,2,LGREEN|_RED,"Print record",'P',WHITE|_RED,NULL);
wmenudef(8,2,LGREEN|_RED,"Update record",'U',WHITE|_RED,NULL);
/* process the menu, load
selection bar at the
definition for 'A' */
17
selection=wmenuget(LRED|_GREEN,'A',0);
wclose(); /* close the window */
Example for a Horizontal Lotus-Style Menu:
int selection;
/* open the window */
wopen(7,15,10,65,0,YELLOW,LCYAN|_BLUE);
/* define the menu */
wmenudef(0,0,LMAGENTA|_BLUE,"Add",'A',WHITE|_BLUE,
"Create a new record");
wmenudef(0,8,LMAGENTA|_BLUE,"Delete",'D',WHITE|_BLUE,
"Delete an existing record");
wmenudef(0,19,LMAGENTA|_BLUE,"Print",'P',WHITE|_BLUE,
"Print hardcopy of existing record");
wmenudef(0,28,LMAGENTA|_BLUE,"Show",'S',WHITE|_BLUE,
"Display an existing record on screen");
wmenudef(0,36,LMAGENTA|_BLUE,"Update",'U',WHITE|_BLUE,
"Modify an existing record");
wmenudef(0,45,LMAGENTA|_BLUE,"Quit",'Q',WHITE|_BLUE,
"Quit program and return to DOS");
wtextattr(LGREEN|_BLUE); /* attribute of text description */
/* process the menu, load the
selection bar at 'A'dd. */
selection=wmenuget(YELLOW|_LGREY,'A',0);
wclose(); /* close the window */
Model for a Complete Pull-Down Menu System:
int m1,m2;
m1='F'; /* init main menu */
m2=PDMAIN;
while(m1) { /* or use " for(;;) { " */
wmenudef( ); /* define main menu */
wmenudef( );
wmenudef( );
m1=wmenuget(attrib,m1,m2); /* get main menu selection */
switch(m1) { /* test main menu selection */
case 'F':
wopen( ); /* open pull-down menu */
m2='L'; /* init pull-down menu */
while(m2>PDMENU) {
wmenudef( ); /* define pull-down menu */
wmenudef( );
wmenudef( );
/* get pull-down menu selection */
m2=wmenuget(attrib,m2,PDMENU);
switch(m2) { /* test pull-down menu selection */
case 'A':
funca();
break
case 'B':
funcb();
break;
18
}
}
wclose(); /* close pull-down menu */
break;
case 'E':
....
break;
case 'D':
....
break;
}
}
19
String Selection Functions.
There are two functions needed for string selection: wsseldef() and
wsselget(). The wsseldef() function defines a string selection record
and is called for every string selection you want to define.
The wsselget() function processes all of the defined string selection
records and returns the address of the string that was selected. The
following keys can be during string selection:
Enter - selects the displayed selection string
LeftArrow - previous selection string
UpArrow - " " "
Shift-Tab - " " "
RightArrow - next selection string
DownArrow - " " "
Tab - " " "
Esc - if Escape checking is on, then pressing this will
cause wsselget() to return NULL and set the global
variable _werrno to W_ESCPRESS. Escape checking is
on by default, but you can use wsetesc(0) to turn it
off.
This is the way it works:
char *prn;
FILE *fpout;
....
wsseldef("PRN"); /* define each possible string */
wsseldef("LPT1");
wsseldef("LPT2");
wsseldef("COM1");
wsseldef("COM2");
wputs("Select printer: "); /* display prompt */
prn=wsselget(YELLOW|_BLUE); /* get selection from keyboard */
if(prn==NULL) { /* test for error */
error_routine();
}
fpout=fopen(prn,"w");
....
What the display would initially look like is:
Select printer: PRN
and by using the arrow keys, you can change the selection. Once Enter
is pressed, the selection will be made.
20
Expanded Memory (EMS) Functions.
CXL contains several functions for simple management of expanded
memory. All of CXL's EMS functions are prefixed with 'ems'. For those
not familiar with expanded memory, I will briefly explain it.
The 8088 microprocessor is only able to address 1 Megabyte of memory.
When applications started needing more memory, Lotus, Intel, and
Microsoft developed the Expanded Memory Specification. This
specification allows access to more than 1 Megabyte of memory by mapping
16K 'windows' of memory on an expanded memory board in and out of an
unused area of DOS memory. The Expanded Memory Manager (EMM) is a
software driver that controls the mapping.
Physical pages are 16K blocks of memory which are located in an unused
area of DOS memory. There are typically 4 physical pages comprising a
64K contiguous area of mappable DOS memory. The EMS page frame base
address points to the beginning of the first physical page. Logical
pages are 16K blocks of memory on the expanded memory board. There can
be as many logical pages as the expanded memory board has, up to 8
Megabytes.
Every program that uses expanded memory must do the following:
1. determine if the EMM device driver is loaded
2. determine if there are enough free pages for its application
3. allocate pages of expanded memory
4. find out what the EMS page frame base address is
5. map logical pages onto physical pages
6. deallocate pages when finished with them
Here's an example of using CXL's EMS functions to perform these
procedures:
int handle1,handle2;
char buf[14];
if(!emsexist()) { /* check for the EMM driver */
printf("EMM not loaded\n");
exit(1);
}
handle1=emsalloc(2); /* request 2 pages of EMS
memory */
handle2=emsalloc(2); /* request 2 more pages */
if(handle1==-1 || handle2==-1) {/* test for allocation error */
printf("EMS allocation error\n");
exit(1);
}
emsmap(handle1,0,0); /* map logical page 0 of handle
1 to physical page 0 */
emswrite("Hello, world",0,13); /* write a string at offset 0,
automatically determines what
the page frame address is */
emsmap(handle2,0,0); /* map logical page 0 of handle
2 to physical page 0 */
emswrite("How are you?",0,13); /* write a string at offset 0 */
21
emsmap(handle1,0,0); /* map logical page 0 of handle
1 to physical page 0 */
emsread(buf,0,13); /* read 13 bytes from offset 0
into buffer */
printf("buf = %s\n",buf); /* display buffer contents */
emsmap(handle2,0,0); /* map logical page 0 of handle
2 to physical page 0 */
emsread(buf,0,13); /* read 13 bytes from offset 0
into buffer */
printf("buf = %s\n",buf); /* display buffer contents */
emsdealloc(handle2); /* deallocate pages belonging
to handle 2 */
emsdealloc(handle1); /* deallocate pages belonging
to handle 1 */
22
Mouse Functions.
CXL has several functions used to facilitate Microsoft compatible mice.
All of these functions are prefixed with am 'ms'. These functions will
work on Microsoft mice or other mice using a Microsoft compatible
driver. These mouse functions allow you to:
1. Initialize mouse/determine if mouse exists.
2. Get the status of button presses/releases.
3. Hide/reveal the mouse cursor.
4. Get/set the mouse cursor position.
5. Select type of mouse cursor (hardware or software).
6. Adjust the mouse sensitivity (speed).
7. Get information on direction of mouse movement.
8. Establish horizontal/vertical boundaries of mouse movement.
When reading or setting mouse coordinates, the values used are in
pixels. To calculate mouse coordinates in terms of column and row
instead of X and Y, you would multiply character width by column, and
character height by row. Typically, screen characters are 8 pixels wide
by 8 pixels tall. So, to position the mouse cursor at column 60, row
15, you would use:
msgotoxy(60*8,15*8);
The mscursor() function sets the cursor type. It takes 3 parameters:
ctype, smask, and cmask. If ctype = 1 then the cursor type is hardware.
The hardware cursor is the flashing block on your screen. If this type
of cursor is used, it will interfere with normal text cursor functions.
When using the hardware cursor type, the value for smask is the start
scan line of the cursor, and the value for cmask is the stop scan line
of the cursor. If the ctype parameter = 0, then a software cursor is
used. For the software cursor, the smask parameter is the screen mask,
and the cmask parameter is the cursor mask. The screen mask determines
which of the characters attributes are preserved. The cursor mask
defines how the attributes are changed to show the cursor. For both
masks, the bit values are as follows:
Bits 0-7: ASCII value of character
Bits 8-10: Foreground color
Bit 11: Intensity
Bits 12-14: Background color
Bit 15: Blink
The msmotion() function determines direction and distance traveled since
last msmotion() call. The xcount and ycount parameters will either be
negative or positive depending on direction mouse moved. The amount
will be the number of pixels travelled.
When updating the screen, the mouse cursor should be hidden with the
mshidecur() function first, and then after the screen is updated, the
msshowcur() should be called to re-display the mouse cursor.
23
GLOBAL VARIABLES
Name: _cgasnow
Purpose: a flag that tells CXL's functions whether or not to use
CGA snow reduction. Defaults to 0 (off). To enable CGA
snow reduction, set this variable to 1.
Type: int
Name: _kbloop
Purpose: points to a procedure to be called while waiting for a
keypress.
Type: void (*) (void)
Name: _mouse
Purpose: this is set by the msinit() function. It contains a zero
if a mouse is not installed or a non-zero if mouse is
installed.
Type: int
Name: _onkey
Purpose: a pointer which points to the highest defined onkey record.
Type: struct _onkey_t * (see CXLKEY.H for definition)
Name: _videoseg
Purpose: contains the current video RAM segment address used by
direct screen writes. Defaults to 0xb800. The videoinit()
function may update this variable.
Type: unsigned int
Name: _werrno
Purpose: contains the error code from the most recently performed
windowing function. See CXLWIN.H for a complete list of
possible error codes.
Type: int
Name: _wesc
Purpose: Escape key checking flag. This is set by the wsetesc()
function and used by several window keyboard input
functions.
Type: int
Name: _whandle
Purpose: contains the last handle number given to a window.
Type: WINDOW
Name: _winp
24
Purpose: a pointer to the highest defined window keyboard input
record.
Type: struct _winp_t * (see CXLWIN.H for definition)
Name: _wmenu
Purpose: a pointer to the highest defined bar-selection menu
record.
Type: struct _wmenu_t * (See CXLWIN.H for definition)
Name: _wrec
Purpose: a pointer to the active window's record.
Type: struct _wrec_t * (see CXLWIN.H for definition)
Name: _wsel
Purpose: a pointer to the highest defined string selection record.
Type: struct _wsel_t * (see CXLWIN.H for definition)
Name: _wtotal
Purpose: contains the total number of open windows
Type: int
25
LIBRARY FUNCTIONS
Name: attrib
Purpose: creates an attribute.
Prototype: int attrib(int fore,int back,int bright,int blink);
Header: cxlvid.h cxlwin.h
Inputs: fore - foreground color code (0-7)
back - background color code (0-7)
bright - intensity (0-1)
blink - blinking (0-1)
Return: attribute
Also see: setattr wtextattr
Example:
prints(15,10,attrib(7,5,1,0),"Hello, world");
Name: beep
Purpose: sounds a beep in the speaker.
Prototype: void beep(void);
Header: cxldef.h cxlvid.h
Inputs: none
Return: none
Also see: sound_
Example:
beep();
Name: biosver
Purpose: returns the ROM BIOS version date.
Prototype: char *biosver(void);
Header: cxldef.h
Inputs: none
Return: address of the static string containing the ROM BIOS
version date
Also see: machid
Example:
printf("ROM BIOS version date is %s\n",biosver());
Name: box_
Purpose: displays a text box on the screen.
Prototype: void box_(int srow,int scol,int erow,int ecol,int btype,
int attr);
Header: cxlvid.h
Inputs: srow - starting row upper left corner
scol - starting column upper left corner
erow - ending row lower right corner
ecol - ending column
btype - box type (0-5)
attr - attribute
Return: none
Also see: boxd
Example:
box_(0,0,22,79,1,WHITE|_BLUE);
26
Name: boxd
Purpose: displays a text box directly on the screen (no BIOS calls).
Prototype: void boxd(int srow,int scol,int erow,int ecol,int btype,
int attr);
Header: cxlvid.h
Inputs: srow - starting row upper left corner
scol - starting column upper left corner
erow - ending row lower right corner
ecol - ending column
btype - box type (0-5)
attr - attribute
Return: none
Also see: box_ videoinit
Example:
boxd(0,0,22,79,1,WHITE|_BLUE);
Name: capsoff
Purpose: toggles the CapsLock key off.
Prototype: void capsoff(void);
Header: cxlkey.h
Inputs: none
Return: none
Also see: capson kbstat numoff
Example:
capsoff();
Name: capson
Purpose: toggles the CapsLock key on.
Prototype: void capson(void);
Header: cxlkey.h
Inputs: none
Return: none
Also see: capsoff kbstat numon
Example:
capson();
Name: clearkeys
Purpose: clears the keyboard buffer.
Prototype: void clearkeys(void);
Header: cxlkey.h
Inputs: none
Return: none
Also see: waitkey
Example:
clearkeys();
Name: clockcal
Purpose: determines if a clock-calendar board is installed (usually
this board will only be in XT machines).
Prototype: int clockcal(void);
Header: cxldef.h
27
Inputs: none
Return: a non-zero value if a clock-calendar board is present
Example:
printf("A clock-calendar is%s installed\n",
clockcal()?"":" not");
Name: clreol_
Purpose: clears to the end of line using current attribute.
Prototype: void clreol_(void);
Header: cxlvid.h
Inputs: none
Return: none
Also see: clrscrn clrwin
Example:
clreol_();
Name: clrscrn
Purpose: clears the screen (up to 50 lines) using current attribute,
and homes the cursor.
Prototype: void clrscrn(void);
Header: cxlvid.h
Inputs: none
Return: none
Also see: clreol_ clrwin
Example:
clrscrn();
Name: clrwin
Purpose: clears a window of the screen using current attribute.
Prototype: void clrwin(srow,scol,erow,ecol);
Header: cxlvid.h
Inputs: srow - starting row upper left corner
scol - starting column upper left corner
erow - ending row lower right corner
ecol - ending column lower right corner
Return: none
Also see: clreol_ clrscrn
Example:
clrwin(11,11,19,19);
Name: cvaltype
Purpose: checks given character against a given CXL character type
code, determines if character is valid type.
Prototype: int cvaltype(int ch,int ctype);
Header: cxlstr.h
Inputs: ch - character to test
ctype - character type code to compare with, see section
on CXL format strings for a list of valid
character type codes.
Return: a 0 if character is not valid, a 1 if character is valid, or
a -1 if invalid ctype was given
zero
Example:
28
int valid=0;
char ch='Z';
valid=cvaltype(ch,'#');
printf("%c is %sa valid char of type '#'\n",ch,
valid?"":" not");
Name: delay_
Purpose: delays program execution for a specified duration.
Prototype: void delay_(unsigned duration);
Header: cxldef.h
Inputs: duration - duration (0-65535) ie. 18 = 1 second
Return: none
Also see: timer waitkeyt
Example:
delay_(36); /* delays for 2 seconds */
Name: disktoscrn
Purpose: copies a previously saved screen disk file back to the
screen.
Prototype: int disktoscrn(char *fname);
Header: cxlvid.h
Inputs: fname - address of the string containing file name to
read from
Return: a zero if no error
Also see: disktowin scrntodisk
Example:
if(disktoscrn("SCREEN.DAT")) {
printf("Error reading input file\n");
exit(1);
}
Name: disktowin
Purpose: copies a previously saved window disk file back to the
screen.
Prototype: int disktowin(char *fname);
Header: cxlwin.h
Inputs: fname - address of the string containing file name to read
from
Return: a zero if no error
Also see: disktoscrn wintodisk
Example:
if(disktowin("WINDOW.DAT")) {
printf("Error reading input file\n");
exit(1);
}
Name: emsalloc
Purpose: allocates pages of EMS memory. See the "Expanded Memory
(EMS) Functions" section for complete details.
Prototype: unsigned emsalloc(int numpages);
Header: cxlems.h
Inputs: numpages - the number of pages (16K blocks) requested
Return: the EMS handle or a -1 if an error occurred
29
Also see: emsdealloc emsexist emsfree
Example:
int emm_handle;
......
emm_handle=emsalloc(2); /* request 2 pages (32K) */
if(emm_handle==-1) {
printf("EMS allocation error\n");
exit(1);
}
Name: emsdealloc
Purpose: deallocate previously allocated pages of EMS memory.
Prototype: int emsdealloc(int handle);
Header: cxlems.h
Inputs: handle - the previously assigned EMS handle
Return: a 0 if no error or else an EMS error code
Also see: emsalloc
Example:
if(emsdealloc(emm_handle)) {
printf("EMS deallocation error\n");
exit(1);
}
Name: emsexist
Purpose: determines if the EMS device driver is loaded. See the
"Expanded Memory (EMS) Functions" section for complete
details.
Prototype: int emsexist(void);
Header: cxlems.h
Inputs: none
Return: a 0 if EMS driver not loaded, or a 1 if EMS driver is loaded
Also see: emsfree emstotal expmem
Example:
printf("EMS device driver is %sloaded\n",
(emsexist())?"":"not ");
Name: emsframe
Purpose: returns the EMS page frame base address (segment).
Prototype: unsigned emsframe(void);
Header: cxlems.h
Inputs: none
Return: the EMS page frame base address (segment) or a zero if an
error occurred
Also see: emsmap
Example:
printf("EMS page frame address is at: %X\n",emsframe());
Name: emsfree
Purpose: returns the number of free EMS pages (16K blocks).
Prototype: unsigned emsfree(void);
Header: cxlems.h
Inputs: none
Return: the number of free EMS pages
30
Also see: emsalloc emstotal
Example:
printf("Free EMS pages: %u\n",emsfree());
Name: emsmap
Purpose: maps a logical EMS page onto a physical page address. The
emsalloc() function must be called prior to this.
Prototype: int emsmap(int handle,int lpage,int ppage);
Header: cxlems.h
Inputs: handle - the EMS handle previosly assigned
lpage - the logical EMS page to map (0 - ?)
ppage - the physical DOS page to map to (0 - 3)
Return: a zero if no error, or else an EMS error code
Also see: emsalloc emsframe
Example:
if(emsmap(ems_handle,0,0)) {
printf("Error mapping logical page 0 "
"to physical page 0\n");
exit(1);
}
Name: emsread
Purpose: reads bytes from an EMS page(s), emsalloc() and emsmap()
must be called prior to this function. The source segment
used will be the current EMS page frame address and the
destination segment will be the program's data segment.
Prototype: int emsread(char *dest,unsigned emsofs,unsigned numbytes);
Header: cxlems.h
Inputs: dest - address to receive bytes read
emsofs - offset from the EMS page frame base address at
which to read the bytes from
numbytes - the number of bytes to read
Return: a zero if no error
Also see: emsmap emswrite
Example:
if(emsread(buf,0x100,64)) {
printf("Failed to read 64 bytes from EMS memory\n");
exit(1);
}
Name: emstotal
Purpose: returns the total number of EMS pages (16K blocks) on the
system.
Prototype: unsigned emstotal(void);
Header: cxlems.h
Inputs: none
Return: the total number of EMS pages on the system or a zero if an
error occurred
Also see: emsfree expmem
Example:
printf("You have %u pages of EMS memory\n",emstotal());
Name: emsver
31
Purpose: returns the current EMS version.
Prototype: char *emsver(void);
Header: cxlems.h
Inputs: none
Return: the address of the static string containing the EMS version
number or NULL if error
Example:
printf("Your EMS version is %s\n",emsver());
Name: emswrite
Purpose: writes bytes to an EMS page(s), emsalloc() and emsmap() must
be called prior to this function. The source segment will
be the program's DATA segment and the destination segment
will be the EMS current EMS page frame address.
Prototype: int emswrite(char *src,unsigned emsofs,unsigned numbytes);
Header: cxlems.h
Inputs: src - address of where to write bytes from
emsofs - offset from EMS page frame base address of where
to write bytes to
numbytes - number of bytes to write
Return: a zero if no error
Also see: emsframe emsmap emsread
Example:
if(emswrite(buf,0x100,64)) {
printf("Failed to write 64 bytes to EMS memory\n");
exit(1);
}
Name: expmem
Purpose: determines the amount (if any) of expanded memory on the
system.
Prototype: unsigned expmem(void);
Header: cxldef.h cxlems.h
Inputs: none
Return: the amount of expanded memory in kilobytes
Also see: emsexist extmem
Example:
printf("Amt of expanded memory = %uK\n",expmem());
Name: extmem
Purpose: determines the amount of extended memory on an AT machine.
Prototype: unsigned extmem(void);
Header: cxldef.h
Inputs: none
Return: the amount of extended memory in kilobytes
Also see: expmem
Example:
printf("Amt of extended memory = %uK\n",extmem());
Name: fill_
Purpose: fills in a region of the screen with specified
character/attribute.
Prototype: void fill_(int srow,int scol,int erow,int ecol,int ch,
32
int attr);
Header: cxlvid.h
Inputs: srow - starting row upper left corner
scol - starting column upper left corner
erow - ending row lower left corner
ecol - ending column lower left corner
ch - character to fill with
attr - attribute of character
Return: none
Also see: attrib filld
Example:
fill_(2,2,9,9,' ',WHITE|_RED);
Name: filld
Purpose: fills in a region of the screen with specified
character/attribute by writing directly to the screen (no
BIOS calls).
Prototype: void filld(int srow,int scol,int erow,int ecol,int ch,
int attr);
Header: cxlvid.h
Inputs: srow - starting row upper left corner
scol - starting column upper left corner
erow - ending row lower left corner
ecol - ending column lower left corner
ch - character to fill with
attr - attribute of character
Return: none
Also see: attrib fill_ videoinit
Example:
filld(2,2,9,9,' ',WHITE|_RED);
Name: gameport
Purpose: determines if a game port is installed.
Prototype: int gameport(void);
Header: cxldef.h
Inputs: none
Return: a zero if game port is not installed, a 1 if installed
Also see: mathchip numflop numpar numser
Example:
printf("Game port is %sinstalled\n",
gameport()?"":"not ");
Name: getchf
Purpose: gets a character from the keyboard from a list of valid
characters, provides Escape checking.
Prototype: int getchf(char *valid,int defchar);
Header: cxlkey.h
Inputs: valid - address of list of valid characters
defchar - default selection in case Enter is pressed, or
a zero for no default
Return: the character pressed or 0 if the Escape key was pressed
Also see: getxch waitkey
Example:
int ch;
33
......
ch=getchf("YyNn",'N');
if(!ch) {
printf("Escape was pressed\n");
exit(1);
}
Name: getns
Purpose: inputs a string of specified length from the keyboard,
provides Escape checking.
Prototype: int getns(char *str,int max);
Header: cxlkey.h
Inputs: str - address of allocated space to receive input string
max - maximum length of the input string
Return: a 1 if the <Esc> key was pressed
Also see: inputsf
Example:
char age[2];
printf("Enter your age: ");
if(getns(age,2)) {
printf("Escape was pressed\n");
exit(0);
}
Name: getxch
Purpose: gets a key (ASCII code/extended ASCII code) from the
keyboard. If a mouse is present and initialized, it
can be used. The mouse movements will translate to
the arrow keys, the left button will translate to
Enter, and the right button will translate to Escape.
Prototype: unsigned getxch(void);
Header: cxlkey.h
Inputs: none
Return: none
Also see: getchf
Example:
unsigned int xch;
......
xch=getxch();
printf("ASCII code = %d, scan code = %d\n",xch,xch>>8);
Name: gotoxy_
Purpose: sets cursor coordinates on the screen.
Prototype: void gotoxy_(int row,int col);
Header: cxlvid.h
Inputs: row - cursor row (Y coordinate)
col - cursor column (X coordinate)
Return: none
Also see: readcur
Example:
gotoxy_(20,30); /* set cursor at row 20, column 30 */
Name: inputsf
34
Purpose: inputs a formatted string from the keyboard.
Prototype: int inputsf(char *str,char *fmt);
Header: cxlkey.h
Inputs: str - address of the allocated space to receive string
fmt - address of the format string, see section on using
format strings
Return: 0 - no error
1 - Escape key was pressed
2 - invalid format string
Also see: getns
Example:
char phone_nr[25];
......
inputsf(phone_nr," !RE! 'Enter phone number: (' ### "
" ') '###'-'#### ");
Name: kbstat
Purpose: returns the status of the keyboard control keys.
Prototype: unsigned kbstat(void);
Header: cxlkey.h
Inputs: none
Return: status word of the keyboard flag. You can determine which
key(s) are being pressed/toggled by masking the status with
one of the following:
RSHIFT - right shift pressed
LSHIFT - left shift pressed
CTRL - <Ctrl> pressed
ALT - <Alt> pressed
SCRLOCK - <Scroll Lock> toggled
NUMLOCK - <Num Lock> toggled
CAPSLOCK - <Caps Lock> toggled
INS - <Ins> toggled
Also see: capsoff capson numoff numon
Example:
if(kbstat()&CTRL) {
printf("The <Ctrl> key is now being pressed\n");
}
Name: lcrlf
Purpose: prints a carriage return and line feed on the printer.
Prototype: void lcrlf(void);
Header: cxlprn.h
Inputs: none
Return: none
Also see: lprintc
Example:
lcrlf();
Name: lprintc
Purpose: prints a character on the printer.
Prototype: void lprintc(int ch);
Header: cxlprn.h
Inputs: ch - the character to print
Return: none
35
Also see: lcrlf lprintf
Example:
lprintc(0x12); /* sends a form-feed to the printer */
Name: lprintf
Purpose: sends formatted output to the printer, works like printf().
Prototype: void lprintf(const char *format,...);
Header: cxlprn.h
Inputs: format - format string, refer to the section on printf() in
the run-time library reference.
... - any additional arguments
Return: none
Also see: lprintc lprintns lprints
Example:
lprintf("%s %c %d\n",str_arg,char_arg,int_arg);
Name: lprintns
Purpose: prints a string on the printer, formatting width.
Prototype: void lprintns(char *str,int width);
Header: cxlprn.h
Inputs: str - the address of the string to print
width - width to print string, uses padding or truncating
Return: none
Also see: lprintf lprints lprintsu
Example:
lprintns("Hello, world",5);
Name: lprints
Purpose: prints a string on the printer.
Prototype: void lprints(char *str);
Header: cxlprn.h
Inputs: str - the address of the string to print
Return: none
Also see: lprintf lprintns lprintsu
Example:
lprints("Hello, world\n");
Name: lprintsb
Purpose: prints a bold-faced string on the printer.
Prototype: void lprintsb(char *str);
Header: cxlprn.h
Inputs: str - the address of the string to print
Return: none
Also see: lprints lprintsu
Example:
lprintsb("Hello, world\n");
Name: lprintsu
Purpose: prints an underlined string on the printer.
Prototype: void lprintsu(char *str);
Header: cxlprn.h
Inputs: str - the address of the string to print
36
Return: none
Also see: lprints lprintsb
Example:
lprintsu("Hello, world\n");
Name: machid
Purpose: returns the value of the machine ROM ID byte.
Prototype: int machid(void);
Header: cxldef.h
Inputs: none
Return: the value of the machine ROM ID byte. Will usually be
one of the following values:
IBMPC - IBM PC
IBMPCXT - IBM PC/XT
IBMPCJR - IBM PCjr
IBMPCAT - IBM PC/AT
IBMPCXT2 - IBM PC/XT-2
IBMCONV - IBM PC Convertible
SPERRYPC - Sperry PC
Also see: biosver
Example:
if(machid()==IBMPCAT) printf("You have an IBM PC/AT\n");
Name: mathchip
Purpose: determines if a math coprocessor is installed.
Prototype: int mathchip(void);
Header: cxldef.h
Inputs: none
Return: a 1 if a math coprocessor is installed
Also see: gameport numflop numpar numser
Example:
printf("Math coprocessor is %sinstalled\n",
mathchip()?"":"not ");
Name: mode
Purpose: sets the video mode.
Prototype: void mode(int mode_code);
Header: cxlvid.h
Inputs: mode_code - mode code number
Return: none
Also see: setlines vidtype
Example:
mode(4); /* sets CGA graphics mode */
Name: msbpress
Purpose: gets info about specific button presses of mouse.
Prototype: void msbpress(int button,int *bstat,int *bcount,int *x,
int *y);
Header: cxlmou.h
Inputs: button - button to check, 0 = left button, 1 = right button
bstat - address to receive button status (0 = not being
pressed, 1 = currently being pressed)
bcount - address to receive number of times pressed since
37
last call
x - address to receive X pixel coordinate at time of
press
y - address to receive Y pixel coordinate at time of
press
Return: none
Also see: msbreles msstatus
Example:
int bstat,bcount,x,y;
......
msbpres(0,&bstat,&bcount,&x,&y);
Name: msbreles
Purpose: gets info about specific button releases of mouse.
Prototype: void msbreles(int button,int *bstat,int *bcount,int *x,
int *y);
Header: cxlmou.h
Inputs: button - button to check, 0 = left button, 1 = right button
bstat - address to receive button status (0 = not being
pressed, 1 = currently being pressed)
bcount - address to receive number of times released since
last call
x - address to receive X pixel coordinate at time of
release
y - address to receive Y pixel coordinate at time of
release
Return: none
Also see: msbpress msstatus
Example:
int bstat,bcount,x,y;
......
msbreles(0,&bstat,&bcount,&x,&y);
Name: mscursor
Purpose: sets the mouse cursor mode.
Prototype: void mscursor(int curtype,int smask,int cmask);
Header: cxlmou.h
Inputs: curtype - cursor type, 0 = software, 1 = hardware
smask - screen mask (SW) or start scan line (HW), see
section on using mouse functions for a
description of mask
cmask - cursor mask (SW) or stop scan line (HW), see
section on using mouse functions for a
description of mask
Return: none
Also see: msshowcur
Example:
mscursor(1,7,1);
Name: msgotoxy
Purpose: sets the mouse coordinates.
Prototype: void msgotoxy(int x,int y);
Header: cxlmou.h
Inputs: x - X pixel coordinate
38
y - Y pixel coordinate
Return: none
Also see: msstatus
Example:
msgotoxy(20*8,10*8); /* sets mouse cursor at row 10,
column 20 */
Name: mshbounds
Purpose: sets the mouse horizontal bounds.
Prototype: void mshbounds(int left,int right);
Header: cxlmou.h
Inputs: left - left pixel boundary
right - right pixel boundary
Return: none
Also see: msvbounds
Example:
/* limits mouse movement between columns 40 and 60 */
mshbounds(40*8,60*8);
Name: mshidecur
Purpose: hides the mouse cursor.
Prototype: void mshidecur(void);
Header: cxlmou.h
Inputs: none
Return: none
Also see: msshowcur
Example:
mshidecur();
Name: msinit
Purpose: determines if mouse is present. If so, initializes mouse
and sets the global variable _mouse to a non-zero value.
See the "Mouse Functions" section for complete details.
Prototype: int msinit(void);
Header: cxlmou.h
Inputs: none
Return: a 0 if mouse is not present
Example:
if(msinit()) {
printf("Mouse initialized!\n");
}
else {
printf("Mouse does not exist\n");
}
Name: msmotion
Purpose: gets information about the movement of mouse.
Prototype: void msmotion(int *xcount,int *ycount);
Header: cxlmou.h
Inputs: xcount - address to receive amount of X movement in pixels
ycount - address to receive amount of Y movement in pixels
Return: none
Example:
39
int xcount,ycount;
......
msmotion(&xcount,&ycount);
Name: msshowcur
Purpose: reveals the mouse cursor.
Prototype: void msshowcur(void);
Header: cxlmou.h
Inputs: none
Return: none
Also see: mshidecur
Example:
msshowcur();
Name: msspeed
Purpose: adjusts mouse speed by changing its sensitivity.
Prototype: void msspeed(int xratio,int yratio);
Header: cxlmou.h
Inputs: xratio - horizontal speed (higher numbers are slower)
yratio - vertical speed (higher numbers are slower)
Return: none
Example:
msspeed(15,15);
Name: msstatus
Purpose: returns the mouse status.
Prototype: void msstatus(int *bstat,int *x,int *y);
Header: cxlmou.h
Inputs: bstat - address to receive button status (0 = not pressed,
1 = pressed)
x - address to receive current X pixel coordinate
y - address to receive current Y pixel coordinate
Return: none
Example:
int bstat,x,y;
......
msstatus(&bstat,&x,&y);
Name: msvbounds
Purpose: sets the mouse vertical bounds.
Prototype: void msvbounds(int top,int bottom);
Header: cxlmou.h
Inputs: top - top pixel boundary
bottom - bottom pixel boundary
Return: none
Also see: mshbounds
Example:
/* limits mouse movement between rows 10 and 20 */
msvbounds(10*8,20*8);
Name: numflop
Purpose: returns the number of floppy disk drives installed.
40
Prototype: int numflop(void);
Header: cxldef.h
Inputs: none
Return: the number of floppy disk drives installed
Also see: gameport mathchip numpar numser
Example:
printf("Number of floppy disk drives = %d\n",
numflop());
Name: numoff
Purpose: toggles the NumLock key off.
Prototype: void numoff(void);
Header: cxlkey.h
Inputs: none
Return: none
Also see: capsoff kbstat numon
Example:
numoff();
Name: numon
Purpose: toggles the NumLock key on.
Prototype: void numon(void);
Header: cxlkey.h
Inputs: none
Return: none
Also see: capson kbstat numoff
Example:
numon();
Name: numpar
Purpose: determines the number of parallel ports.
Prototype: int numpar(void);
Header: cxldef.h
Inputs: none
Return: the number of parallel ports installed
Also see: gameport mathchip numflop numser
Example:
printf("Number of parallel ports = %d\n",
numpar());
Name: numser
Purpose: determines the number of serial ports installed.
Prototype: int numser(void);
Header: cxldef.h
Inputs: none
Return: the number of serial ports installed
Also see: gameport mathchip numflop numpar
Example:
printf("Number of serial ports = %d\n",
numser());
Name: printc
41
Purpose: prints a character to the screen at a specified location and
attribute.
Prototype: void printc(int row,int col,int attr,int ch,int count);
Header: cxlvid.h
Inputs: row - row
col - column
attr - attribute of character
ch - character to print
count - number of times to print character
Return: none
Also see: attrib printcd
Example:
printc(18,60,LGREEN|BLINK,'Z',5);
Name: printcd
Purpose: prints a character directly to the screen at a specified
location and attribute (no BIOS calls).
Prototype: void printcd(int row,int col,int attr,int ch);
Header: cxlvid.h
Inputs: row - row
col - column
attr - attribute of character
ch - character to print
Return: none
Also see: attrib printc videoinit
Example:
printcd(18,60,LGREEN|BLINK,'Z');
Name: prints
Purpose: displays a string on the screen at a specified location
and attribute.
Prototype: void prints(int row,int col,int attr,char *str);
Header: cxlvid.h
Inputs: row - cursor row
col - cursor column
attr - character attribute
str - address of string to display
Return: none
Also see: attrib printsd
Example:
prints(20,10,LRED|_LGREY,"Hello, world");
Name: printsd
Purpose: displays a string at a specified location in a specified
attribute directly on the screen (no BIOS calls).
Prototype: void printsd(int row,int col,int attr,char *str);
Header: cxlvid.h
Inputs: row - cursor row
col - cursor column
attr - character attribute
str - address of string to display
Return: none
Also see: attrib prints videoinit
Example:
42
printsd(20,10,LRED|_LGREY,"Hello, world");
Name: readchat
Purpose: reads the character and attribute under the cursor.
Prototype: int readchat(void);
Header: cxlvid.h
Inputs: none
Return: integer containing character in low byte and attribute in
high byte
Also see: revattr setattr
Example:
int i;
......
i=readchat();
printf("character is %c and attribute is %d\n",i,(i>>8));
Name: readcur
Purpose: reads the current cursor location.
Prototype: void readcur(int *row,int *col);
Header: cxlvid.h
Inputs: row - address of location to receive cursor row
col - address of location to receive cursor column
Return: none
Also see: gotoxy_
Example:
int row,col;
......
readcur(&row,&col);
Name: revattr
Purpose: reverses the attribute of the character under the current
cursor location, continues for the specified number of
characters.
Prototype: void revattr(int count);
Header: cxlvid.h
Inputs: count - the number of characters to reverse attribute of
Return: none
Also see: readchat setattr
Example:
revattr(5);
Name: scrndump
Purpose: dumps the current screen to the printer.
Prototype: void scrndump(void);
Header: cxlprn.h
Inputs: none
Return: none
Also see: scrntodisk ssave videoinit
Example:
scrndump();
Name: scrntodisk
43
Purpose: copies the current screen to a disk file.
Prototype: int scrntodisk(char *fname);
Header: cxlvid.h
Inputs: fname - address of the string containing file to write to
Return: a zero if no error
Also see: disktoscrn scrndump ssave wintodisk
Example:
if(scrntodisk("SCREEN.DAT")) {
printf("Error creating file\n");
exit(1);
}
Name: setattr
Purpose: sets the attribute of the character under the current cursor
location, continues for the specified number of characters.
Prototype: void setattr(int attr,int count);
Header: cxlvid.h
Inputs: attr - attribute to set character
count - the number of characters to set the attribute of
Return: none
Also see: attrib readchat revattr
Example:
setattr(LRED|BLINK,5);
Name: setcursz
Purpose: sets the cursor size.
Prototype: void setcursz(int sline,int eline);
Header: cxlvid.h
Inputs: sline - start line of cursor (32 for no cursor)
eline - end line of cursor
Return: none
Example:
setcursz(1,7); /* makes a large cursor */
Name: setkbloop
Purpose: sets a procedure that will be called while waiting for
a keypress.
Prototype: void setkbloop( void (*func) (void));
Header: cxlkey.h
Inputs: func - address of the procedure to be called while
waiting for keypress or NULL to cancel the
procedure.
Return: none
Also see: waitkey waitkeyt
Example:
setkbloop(myfunc);
Name: setlines
Purpose: sets the number of lines on the display.
Prototype: int setlines(int numlines);
Header: cxlvid.h
Inputs: numlines - the number of lines to set the display to,
valid numbers are 25 for all video adapters,
44
43 for EGA, and 50 for VGA.
Return: zero if no error
Also see: mode vidtype
Example:
if(setlines(43)) {
printf("You need an EGA monitor for 43-line mode\n");
}
else {
printf("You are now in EGA 43-line mode\n");
}
Name: setonkey
Purpose: attaches/detaches a keypress to a function call. Works by
intercepting any calls to CXL keyboard input functions.
Whenever you use one of CXL's keyboard input functions, the
input function will check to see if the pressed key has been
defined. If so, then the input function will call the
corresponding function. If not, then the input function
will pass on the keypress as normal. This function can be
used for simple context sensitive help by defining the help
key for one procedure and redefining for the next.
Prototype: int setonkey(unsigned keycode,void (*func) (void),int pass);
Header: cxlkey.h
Inputs: keycode - scan code/ASCII code of the keypress to define. If
the keycode was previous defined, it will be
re-defined. The scan code must be in the upper 8
bits and the ASCII code must be in the lower 8
bits. This is easily accomplished using a scan
code/ASCII code reference table and using the hex
values for both codes. For example, the Escape
key has a scan code of 0x01 and an ASCII code of
0x1b, so the value you would input for keycode
would be 0x011b.
func - address of the function to call upon keypress.
The called function must have the prototype:
void func(void);
If NULL is specified for func, then the specified
keycode will be un-defined.
pass - pass the keypress on to the caller? 0=no, 1=yes
After the function corresponding to the defined
keypress has been called, the keyboard input
function can pass on the keypress to its caller or
it can wait for another keypress.
Return: a zero if no error, otherwise a memory allocation error
Example:
/* attaches Ctrl-T to myfunc() */
setonkey(0x1414,myfunc,0);
Name: sound_
Purpose: sounds a tone of specified pitch and duration.
Prototype: void sound_(unsigned pitch,unsigned duration);
Header: cxldef.h
Inputs: pitch - pitch of tone (0-65535)
duration - duration of tone (0-65535) ie. 18 = 1 second
Return: none
45
Also see: beep
Example:
sound_(255,3);
Name: spc
Purpose: displays a specified number of spaces to the screen.
Prototype: void spc(int num);
Header: cxlvid.h
Inputs: num - number of spaces to display
Return: none
Example:
spc(3);
Name: srestore
Purpose: restores a previously saved screen.
Prototype: void srestore(int *sbuf);
Header: cxlvid.h
Inputs: sbuf - address of previously saved screen buffer
Return: none
Also see: ssave videoinit wrestore
Example:
srestore(sbuf);
Name: ssave
Purpose: saves the current screen to a buffer.
Prototype: int *ssave(void);
Header: cxlvid.h
Inputs: none
Return: address of newly created screen buffer or 0 if allocation
error
Also see: scrndump scrntodisk srestore videoinit wsave
Example:
int *sbuf;
......
sbuf=ssave();
if(!sbuf) {
printf("Memory allocation error\n");
exit(1);
}
Name: strblank
Purpose: determines if a given string is blank (whitespace)
Prototype: int strblank(char *str);
Header: cxlstr.h
Inputs: str - address of the string to check
Return: a 0 if not blank, a 1 if blank
Example:
char *str=" ";
printf("str is %sblank\n",strblank(str)?"":"not ");
Name: strbmatch
Purpose: returns the best match of a string in an array of strings.
46
Prototype: char *strbmatch(char *str,char *strarr[]);
Header: cxlstr.h
Inputs: str - address of string to match
strarr - address of array of string pointers, the last
pointer in the array must be NULL
Return: address of the string in the array that best matched the
given string.
Also see: strmatch
Example:
char *strarr[]= { "Hello","Computer","World",NULL };
char *str="xhelpx";
printf("best match is: %s\n",strbmatch(str,strarr));
Name: strchg
Purpose: finds all letters in a string matching one character and
replaces them with another.
Prototype: int strchg(char *str,int oldch,int newch);
Header: cxlstr.h
Inputs: str - address of string to search
oldch - character to search for
newch - character to replace with
Return: the number of matches found
Also see: strichg
Example:
char *str="Hello there";
printf("Before: %s\n",str);
strchg(str,'h','*');
printf("After: %s\n",str);
Name: strcode
Purpose: encodes/decodes a string. Call this function to encode a
string, then call again using the same key to decode. When
reading or writing from a disk file, be sure to open the
file in binary mode.
Prototype: char *strcode(char *str,char *key);
Header: cxlstr.h
Inputs: str - the address of the string to encode/decode
key - the address of the key string to encode/decode with.
The string can consist of any valid characters
(1-255) and can be of any length. Remember this key
or your data will be lost forever!
Return: the address of the encoded/decoded string
Example:
char *str="Hello, world";
printf("Before: %s\n",str);
strcode(str,"m{&!\xfc");
printf("Encoded: %s\n",str);
strcode(str,"m{&!\xfc");
printf("Decoded: %s\n",str);
Name: strdel
Purpose: deletes a substring from within a string.
Prototype: char *strdel(char *substr,char *str);
Header: cxlstr.h
47
Inputs: substr - address of substring to delete
str - address of string to delete from
Return: a NULL if the substring was not found, or the address of the
modified string.
Also see: stridel strinc strins strmid
Example:
char *str="Hello, XXXXXworld";
strdel("XXXXX",str);
printf("%s\n",str);
Name: strichg
Purpose: finds all letters in a string matching one character and
replaces them with another, ignoring case of letters.
Prototype: int strichg(char *str,int oldch,int newch);
Header: cxlstr.h
Inputs: str - address of string to search
oldch - character to search for
newch - character to replace with
Return: the number of matches found
Also see: strchg
Example:
char *str="Hello there";
printf("Before: %s\n",str);
strichg(str,'h','*');
printf("After: %s\n",str);
Name: stridel
Purpose: deletes a substring from within a string, ignoring case of
letters.
Prototype: char *stridel(char *substr,char *str);
Header: cxlstr.h
Inputs: substr - address of substring to delete
str - address of string to delete from
Return: a NULL if the substring was not found, or the address of the
modified string
Also see: strdel striinc
Example:
char *str="Hello, XXXXXworld";
stridel("XXXXX",str);
printf("%s\n",str);
Name: striinc
Purpose: determines if one string is included in another, ignoring
case of letters.
Prototype: char *striinc(char *str1,char *str2);
Header: cxlstr.h
Inputs: str1 - address of string1
str2 - address of string2
Return: the address where string1 is included in string2, or a NULL
if string1 is not included in string2
Also see: strinc strmid
Example:
char *str1="HeLlo WOrLd";
char *str2="XXXXXXXHello, worldXXXXX";
48
if(striinc(str1,str2)) {
printf("%s is included in %s\n",str1,str2);
}
Name: strinc
Purpose: determines if one string is included in another.
Prototype: char *strinc(char *str1,char *str2);
Header: cxlstr.h
Inputs: str1 - address of string1
str2 - address of string2
Return: the address where string1 is included in string2, or a NULL
if string1 is not included in string2
Also see: striinc strmid
Example:
char *str1="Hello world";
char *str2="XXXXXXXHello, worldXXXXX";
if(strinc(str1,str2)) {
printf("%s is included in %s\n",str1,str2);
}
Name: strins
Purpose: inserts one string into another.
Prototype: char *strins(char *instr,char **str,int st_pos);
Header: cxlstr.h
Inputs: instr - the address of the string to insert
str - the address of the address of the string to
insert into
st_pos - the starting position for where to insert
Return: the address of the newly allocated string, or a NULL if a
memory allocation error occurred
Also see: strdel strinc
Example:
char *str="Hello!";
printf("%s\n",str);
strins(", world",&str,5);
printf("%s\n",str);
free(str); /* free memory when done with string */
Name: striocc
Purpose: returns the number of occurrences of a character in a string
ignoring the case of letters.
Prototype: int striocc(char *str,int ch);
Header: cxlstr.h
Inputs: str - address of the string to search
ch - the character to look for
Return: the number of occurrences of the character in the string
Also see: strocc
Example:
char ch='L';
char *str="Hello, world";
printf("%c occurs in %s %d times\n",ch,str,
striocc(str,ch));
49
Name: strleft
Purpose: takes a specified portion of a string from the left and
creates a new string.
Prototype: char *strleft(char *str,int num_chars);
Header: cxlstr.h
Inputs: str - address of input string
num_chars - number of characters to copy
Return: address of the newly created string or a NULL if a memory
allocation error occurred
Also see: strmid strright strtrim
Example:
char *left;
char *str="Hello, worldXXXX";
left=strleft(str,12);
printf("%s\n",left);
free(left); /* free memory when done with string */
Name: strltrim
Purpose: trims leading spaces off of a string.
Prototype: char *strtrim(char *str);
Header: cxlstr.h
Inputs: str - address of the string to trim
Return: address of the modified string
Also see: strright strsetsz strtrim
Example:
char *str=" Hello, world";
printf("Before: %s.\n",str);
strltrim(str);
printf("After: %s.\n",str);
Name: strmatch
Purpose: compares 2 strings, returns a match score.
Prototype: int strmatch(char *str1,char *str2);
Header: cxlstr.h
Inputs: str1 - address of first string
str2 - address of second string
Return: a match score, the higher the score, the better they match
Also see: strbmatch
Example:
char *str1="hello";
char *str2="help";
printf("match score = %d\n",strmatch(str1,str2));
Name: strmid
Purpose: takes a section from input string starting at given position
and taking the given amount of characters creating a new
string.
Prototype: char *strmid(char *str,int st_pos,int num_chars);
Header: cxlstr.h
Inputs: str - address of input string
st_pos - position in input string to start copying
characters (starting at position 0)
num_chars - number of characters to copy
Return: address of the newly created string or a NULL if a memory
50
allocation error occurred
Also see: strleft strright
Example:
char *middle;
char *str="XXXXXHello, worldXXXX";
middle=strmid(str,5,12);
printf("%s\n",middle);
free(middle); /* free memory when done with string */
Name: strocc
Purpose: returns the number of occurrences of a character in a
string.
Prototype: int strocc(char *str,int ch);
Header: cxlstr.h
Inputs: str - address of the string to search
ch - the character to look for
Return: the number of occurrences of the character in the string
Also see: striocc
Example:
char ch='l';
char *str="Hello, world";
printf("%c occurs in %s %d times\n",ch,str,strocc(str,ch));
Name: strright
Purpose: takes a specifed portion from the right side of a string
creating a new string.
Prototype: char *strright(char *str,int num_chars);
Header: cxlstr.h
Inputs: str - address of input string
num_chars - number of characters to copy
Return: address of the newly created string or a NULL if a memory
allocation error occurred
Also see: strleft strltrim strmid
Example:
char *right;
char *str="XXXXXHello, world";
right=strright(str,12);
printf("%s\n",right);
free(right); /* free memory when done with string */
Name: strrol
Purpose: rotates a string specified number of characters left,
characters wrap around.
Prototype: char *strrol(char *str,int count);
Header: cxlstr.h
Inputs: str - the address of the string to rotate
count - number of characters to rotate
Return: the address of the modified string
Also see: strror strshl
Example:
char *str="Hello, world";
printf("Before: %s.\n",str);
strrol(str,3);
printf("After: %s.\n",str);
51
Name: strror
Purpose: rotates a string specified number of characters right,
characters wrap around.
Prototype: char *strror(char *str,int count);
Header: cxlstr.h
Inputs: str - the address of the string to rotate
count - number of characters to rotate
Return: the address of the modified string
Also see: strrol strshr
Example:
char *str="Hello, world";
printf("Before: %s.\n",str);
strror(str,3);
printf("After: %s.\n",str);
Name: strsetsz
Purpose: adjusts the length of a string by truncation or padding with
spaces.
Prototype: char *strsetsz(char **str,int newsize);
Header: cxlstr.h
Inputs: str - address of pointer to the string
newsize - the new length of the string
Return: address of the new string or a NULL if a memory allocation
error occurred.
Also see: strtrim
Example:
char *str="Hello, world";
strsetsz(&str,25);
printf("%s.\n",str);
strsetsz(&str,5);
printf("%s.\n",str);
Name: strshl
Purpose: shifts a string specified number of characters left,
characters 'drop off' and spaces are added to the string.
Prototype: char *strshl(char *str,int count);
Header: cxlstr.h
Inputs: str - the address of the string to shift
count - number of characters to shift
Return: the address of the modifed string
Also see: strrol strshr
Example:
char *str="Hello, world";
printf("Before: %s.\n",str);
strshl(str,3);
printf("After: %s.\n",str);
Name: strshr
Purpose: shifts a string specified number of characters right,
characters 'drop off' and spaces are added to the string.
Prototype: char *strshr(char *str,int count);
Header: cxlstr.h
52
Inputs: str - the address of the string to shift
count - number of characters to shift
Return: the address of the modified string
Also see: strror strshl
Example:
char *str="Hello, world";
printf("Before: %s.\n",str);
strshr(str,3);
printf("After: %s.\n",str);
Name: strtrim
Purpose: trims trailing spaces off of a string.
Prototype: char *strtrim(char *str);
Header: cxlstr.h
Inputs: str - address of the string to trim
Return: address of the modified string
Also see: strleft strltrim strsetsz
Example:
char *str="Hello, world ";
printf("Before: %s.\n",str);
strtrim(str);
printf("After: %s.\n",str);
Name: struplow
Purpose: converts a string to mixed upper & lower case characters.
Prototype: char *struplow(char *str);
Header: cxlstr.h
Inputs: str - the address of the string to convert
Return: the address of the modified string
Also see: touplow
Example:
char *str="heLlO, wOrLd";
printf("Before: %s.\n",str);
struplow(str);
printf("After: %s.\n",str);
Name: sysdate
Purpose: returns a string containing the current system date.
Prototype: char *sysdate(int dtype);
Header: cxldef.h
Inputs: dtype - date type code. Can be one of the following:
Code Example
---- -------
0 December 3, 1988
1 3 Dec 88
2 12-3-88
3 12/3/88
4 3/12/88
Return: the address of the static string containing the system date.
Also see: systime
Example:
printf("The system date is: %s\n",sysdate(0));
53
Name: systime
Purpose: returns a string containing the system time.
Prototype: char *systime(int ttype);
Header: cxldef.h
Inputs: ttype - time type code. Can be one of the following:
Code Example
---- -------
0 16:30:57.89
1 16:30:57
2 4:30 PM
3 4:30p
4 4:30
Return: the address of the static string containing the system time.
Also see: sysdate
Example:
printf("The current system time is: %s\n",systime(2));
Name: tabstop
Purpose: calculates a tab stop from given column and tab width.
Prototype: int tabstop(int col,int tabwidth);
Header: cxldef.h
Inputs: col - column
tabwidth - tab width
Return: the next tab stop column
Example:
printf("The next tab stop after column 5 is %d\n",
tabstop(5,8));
Name: timer
Purpose: returns the value of the BIOS timer.
Prototype: unsigned long timer(void);
Header: cxldef.h
Inputs: none
Return: current value of the BIOS timer
Also see: delay_
Example:
printf("%lu\n",timer());
delay_(36);
printf("%lu\n",timer());
Name: touplow
Purpose: converts a character to upper or lower case depending on
previous character.
Prototype: int touplow(char *str,char *pos,int ch);
Header: cxlstr.h
Inputs: str - address of string
pos - current position in string
ch - character to convert
Return: the converted character
Also see: struplow
Example:
char *str="Hello, world";
printf("Before: %s\n",str);
*(str+7)=touplow(str,str+7,*(str+7));
54
printf("After: %s\n",str);
Name: videoinit
Purpose: initializes CXL's video system. By default all CXL
functions performing direct screen writes go to the CGA
video RAM segment at 0xb800. If you want these functions to
work correctly with a monochrome video adapter or within a
DESQview window, you must call this function. This function
sets the value of the global variable _videoseg.
Prototype: void videoinit(void);
Header: cxlvid.h cxlwin.h
Inputs: none
Return: none
Also see: vidtype
Example:
videoinit();
Name: vidtype
Purpose: determines the display adapter type.
Prototype: int vidtype(void);
Header: cxlvid.h
Inputs: none
Return: video adapter type. Will be one of the following values:
MDA - Monochrome Display Adapter
HGC - Hercules Graphics Card
HGCPLUS - Hercules Graphics Card Plus
INCOLOR - Hercules InColor card
CGA - Color Graphics Adapter
EGA - Enhanced Graphics Adapter
VGA - Video Graphics Array adapter
Also see: mode videoinit
Example:
int vid_adapt;
vid_adapt=vidtype();
if(vid_adapt>HGCPLUS) {
printf("A color adapter is installed\n");
}
Name: wactiv
Purpose: activates a previously opened window.
Prototype: int wactiv(WINDOW whandle);
Header: cxlwin.h
Inputs: whandle - the window handle returned from the wopen()
function
Return: W_NOERROR - no error
W_NOTFOUND - window handle not found
W_NOACTIVE - no open windows
Also see: wisactiv wopen
Example:
int window_handle;
......
wactiv(window_handle);
55
Name: waitkey
Purpose: halts execution until a key is pressed, the keyboard buffer
is cleared first.
Prototype: int waitkey(void);
Header: cxlkey.h
Inputs: none
Return: the ASCII value of the key pressed
Also see: clearkeys getchf waitkeyt
Example:
waitkey();
Name: waitkeyt
Purpose: halts execution until a key is pressed or the specified time
limit expires, the keyboard buffer is cleared first.
Prototype: int waitkeyt(int duration);
Header: cxlkey.h
Inputs: duration - length of time to wait for keypress (18 = 1 sec)
Return: the ASCII value of the key pressed or a -1 if time expired
Also see: clearkeys delay_ getchf waitkey
Example:
waitkeyt(182); /* wait for a max of 10 seconds */
Name: waitvret
Purpose: waits for vertical retrace on CGA adapters. This is useful
for writing your own routines that access the screen memory
directly. Calling this first will give you at least 512
bytes of snow-free direct screen memory access. The faster
your machine is, the more bytes you can move during vertical
retrace. Although setting CXL's _cgasnow variable to 1
reduces snow, it doesn't eliminate it. You can use this
function for "problem sections" of your code.
Prototype: void waitvret(void);
Header: cxlvid.h
Inputs: none
Return: none
Example:
if(_cgasnow) waitvret();
Name: wblocked
Purpose: determines if a window is being blocked by any other
windows.
Prototype: int wblocked(WINDOW whandle);
Header: cxlwin.h
Inputs: whandle - handle of window to check
Return: -1 - error. The global variable _werrno will be set to
one of the following:
W_NOACTIVE - no active window
W_NOTFOUND - window handle not found
0 - window is not blocked
1 - window is blocked
Also see: wisactiv
Example:
WINDOW w1,w2;
w1=wopen(0,0,10,20,0,LCYAN|_BLUE,LCYAN|_BLUE);
56
w2=wopen(8,8,15,40,0,LMAGENTA|_RED,LMAGENTA|_RED);
wopen(5,45,15,75,0,YELLOW|_GREEN,YELLOW|_GREEN);
printf("the blue window is %sblocked\n",
wblocked(w1)?"":"not ");
printf("the red window is %sblocked\n",
wblocked(w2)?"":"not ");
Name: wborder
Purpose: changes the active window's border box type.
Prototype: int wborder(int btype);
Header: cxlwin.h
Inputs: btype - box type (0-5). Use btype 5 for a borderless
window.
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVBTYPE - invalid box type
Example:
wborder(1);
Name: wbox
Purpose: displays a text box in active window.
Prototype: int wbox(int wsrow,int wscol,int werow,int wecol,int btype,
int attr);
Header: cxlwin.h
Inputs: wsrow - window start row
wscol - window start column
werow - window end row
wecol - window end column
btype - box type (0-5)
attr - attribute
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
Also see: wfill whline wvline
Example:
wbox(2,2,10,20,0,LMAGENTA|_RED);
Name: wcclear
Purpose: clears the currently active window using specified
attribute.
Prototype: int wcclear(int attr);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wclear wclreol wclreos
Example:
wcclear(LBLUE|_RED);
Name: wcenters
Purpose: displays a string centered in active window.
Prototype: int wcenters(int wrow,int attr,char *str);
Inputs: wrow - window row
57
attr - attribute
str - address of string to display
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid window row
W_STRLONG - string too long to be centered in window
Also see: wprints wrjusts
Example:
wcenters(2,LBLUE,"Hello, world");
Name: wchgattr
Purpose: changes attribute of the active window, all text within the
window will be changed also.
Prototype: int wchgattr(int battr,int wattr);
Header: cxlwin.h
Inputs: battr - the attribute to make the window's border
wattr - the attribute to make the window
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wtextattr
Example:
wchgattr(LMAGENTA|_RED,YELLOW|_BLUE);
Name: wclear
Purpose: clears the currently active window.
Prototype: int wclear(void);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wcclear wclreol wclreos
Example:
wclear();
Name: wclose
Purpose: closes the currently active window.
Prototype: int wclose(void);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wcloseall wopen
Example:
wclose();
Name: wcloseall
Purpose: closes all open windows.
Prototype: int wcloseall(void);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wclose
58
Example:
wcloseall();
Name: wclreol
Purpose: clears to the end of the active window's line.
Prototype: int wclreol(void);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wclear wclreos
Example:
wclreol();
Name: wclreos
Purpose: clears from current cursor position to the end of
the active window.
Prototype: int wclreos(void);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wclear wclreol
Example:
wclreos();
Name: wcopy
Purpose: creates a new window duplicating the active window, the new
window becomes the active window.
Prototype: WINDOW wcopy(int nsrow,int nscol);
Header: cxlwin.h
Inputs: nsrow - start row of the duplicate window
nscol - start column of the duplicate window
Return: the handle of the new window or a zero if an error occurred.
If error, the global variable _werrno will be set to one of
the following: W_ALLOCERR - memory allocation error
W_INVCOORD - invalid coordinates
Also see: wactiv wmove wopen
Example:
wcopy(10,20); /* make copy of active window at
row 10, col 20 */
Name: wdelline
Purpose: deletes a line in active window
Prototoype: int wdelline(int wrow,int direc);
Header: cxlwin.h
Inputs: wrow - window row to delete
direc - scroll direction:
SUP - scroll up
SDOWN - scroll down
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid window row
59
Also see: winsline wscroll
Example:
wdelline(4,SDOWN);
Name: wdupc
Purpose: displays a character specified number of times in active
window. Characters will be displayed in the attribute set
by the wtextattr() function. Control characters are
recognized. Cursor position is updated.
Prototype: int wdupc(int ch,int count);
Header: cxlwin.h
Inputs: ch - character to be displayed
count - number of times to display character
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wputc
Example:
wdupc('X',5); /* displays 'X' 5 times */
Name: werrmsg
Purpose: returns an error message from the last windowing function.
Prototype: char *werrmsg(void);
Header: cxlwin.h
Inputs: none
Return: the address of a static string containing an error message
corresponding to the error code from the last performed
windowing function.
Also see: wperror
Example:
wgotoxy(255,255); /* invalid coordinates */
printf("Error message = %s\n",werrmsg());
Name: wfill
Purpose: fills in a region of active window with specified character
and attribute.
Prototype: int wfill(int wsrow,int wscol,int werow,int wecol,int ch,
int attr);
Header: cxlwin.h
Inputs: wsrow - window start row
wscol - window start column
werow - window end row
wecol - window end column
ch - character to fill with
attr - attribute
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
Also see: wbox
Example:
wfill(2,2,10,20,'Z',LMAGENTA|_RED);
Name: wfindrec
Purpose: finds the address of the window record of the specified
60
window handle.
Prototype: struct _wrec_t *wfindrec(WINDOW whandle);
Header: cxlwin.h
Inputs: whandle - window handle of window record to find
Return: the address of the found window record or NULL if no record
was found for specified handle.
Example:
struct _wrec_t *wrecptr;
....
wrecptr=wfindrec(3);
Name: wgetc
Purpose: gets a character from the keyboard within the active window,
echos character pressed to the screen in the attribute set
by the wtextattr() function.
Prototype: int wgetc(void);
Header: cxlwin.h
Inputs: none
Return: the ASCII value of the key pressed or a zero if an error
occurred. If error, the global variable _werrno will be set
to one of the following:
W_NOACTIVE - no active window
Also see: wgetchf wscanf wtextattr
Example:
int ch;
......
ch=wgetc();
Name: wgetchf
Purpose: gets a character from the keyboard within the active window,
allows only characters listed in the string of valid
characters. Escape checking is provided by default. This
can be turned off with the wsetesc() function. Selected
character is echoed into the current window using the
attribute set by the wtextattr() function.
Prototype: int wgetchf(char *valid,int defchar);
Header: cxlwin.h
Inputs: valid - address of the string containing the valid
characters
defchar - default selection in case Enter is pressed, or a
zero for no default
Return: the ASCII value of the key pressed or a zero if an error
occurred. If error, the global variable _werrno will be set
to one of the following:
W_NOACTIVE - no active window
W_ESCPRESS - Escape key was pressed
Also see: wgetc wscanf wtextattr
Example:
int ch;
......
ch=wgetchf("YyNn",'N');
if(_werrno==W_ESCPRESS) {
printf("Escape key was pressed\n");
exit(1);
}
61
Name: wgetns
Purpose: gets a string from the keyboard within active window, limits
the number of characters input to specified length. Escape
checking is provided by default. This can be turned off
with the wsetesc() function. Entered characters will echo
to the active window in the attribute set by the wtextattr()
function.
Prototype: int wgetns(char *str,int maxlen);
Header: cxlwin.h
Inputs: str - address of the allocated space to receive the
input string
maxlen - the maximum length of the input string
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - Escape key was pressed
Also see: wgets winputsf wscanf wsetesc wtextattr
Example:
char fname[20];
......
wputs("Enter your first name: ");
wgetns(fname,5);
Name: wgets
Purpose: gets a string from the keyboard within active window, echos
the characters to the screen in the attribute set by the
wtextattr() function.
Prototype: int wgets(char *str);
Header: cxlwin.h
Inputs: str - the address of the allocated memory to receive the
input string
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wgetns winputsf wscanf wtextattr
Example:
char fname[20];
......
wputs("Enter your first name: ");
wgets(fname);
Name: wgotoxy
Purpose: sets cursor coordinates within the currently active window.
Prototype: int wgotoxy(int wrow,int wcol);
Header: cxlwin.h
Inputs: wrow - window row (Y coordinate)
wcol - window column (X coordinate)
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
Also see: wpgotoxy wreadcur
Example:
wgotoxy(2,3); /* set cursor to row 2, column 3 */
62
Name: whandle
Purpose: returns the handle of the active window
Prototype: WINDOW whandle(void);
Header: cxlwin.h
Inputs: none
Return: the handle of the active window or zero if error. If error,
the global variable _werrno will be set to one of the
following: W_NOACTIVE - no active window
Also see: wactiv wisactiv
Example:
printf("active handle = %d\n",whandle());
Name: whide
Purpose: hides a previously saved window.
Prototype: int *whide(int **wbuf);
Header: cxlwin.h
Inputs: wbuf - address of the pointer to the window buffer to
hide
Return: the address of the hidden window's buffer or a NULL if a
memory allocation error occurred.
Also see: wsave wunhide
Example:
/* hides active window */
if(!whide(_wrec->wbuf)) {
printf("Memory allocation error\n");
exit(1);
}
Name: whline
Purpose: draws a horizontal text line in active window using
characters defined by given box type. If horizontal line
crosses a vertical line of the same box type, an appropriate
intersection or corner will be used.
Prototype: int whline(int wsrow,int wscol,int count,int btype);
Header: cxlwin.h
Inputs: wsrow - window start row of line
wscol - window start column of line
count - number of line characters to display
btype - box type (0-5)
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - text line too long for window
W_INVBTYPE - invalid box type
Also see: wtextattr wvline
Example:
whline(2,5,7,3);
Name: winpdef
Purpose: defines an area of the active window for keyboard input. See
the section "Multi-Field Formatted Input Functions" for the
complete details.
Prototype: int winpdef(int wrow,int wcol,char *str,char *format,
int fconv,int fattr,int update,
int (*validate) (char *));
63
Header: cxlwin.h
Inputs: wrow - start of input, window's row coordinate
wcol - start of input, window's column coordinate
str - address of string buffer to receive input
format - input field format string
fconv - input field conversion character. Applies
conversion to all letters in the input field. Can
be one of the following:
0 - apply no conversion
'L' - convert letters to lower case
'M' - convert letters to mixed case
'P' - password field (no echo)
'U' - convert letters to upper case
fattr - field attribute
update - update pre-existing field? 0 = no, 1 = yes
validate - address of your user validation/modification
function. The function must be declared like:
int func(char *str);
Your user function will receive the field input
from the keyboard and will return zero if no
error. If there was an error, then your function
will return the position of the error in the
string (starting at 1, not 0). If you do not
wish to validate the field, then input NULL.
Return: W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
W_INVFORMT - invalid format string
W_LENFORMT - length of format string is invalid
Also see: winpread winputsf wscanf
Example:
char name[11];
......
wputs("Enter name:");
winpdef(1,13,name,"MMMMMMMMMM",0,LCYAN|_BLUE,0,NULL);
Name: winpread
Purpose: processes keyboard input of all defined areas of active
window allowing editing back and forth between defined
fields. See the section "Multi-Field Formatted Input
Functions" for the complete details.
Prototype: int winpread(void);
Header: cxlwin.h
Inputs: none
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - Escape key was pressed
W_NOINPDEF - no inputs defined
Also see: winpdef wsetesc wtextattr
Example:
winpread();
Name: winputsf
Purpose: inputs a formatted string from the keyboard within a window.
64
Input characters will be echoed to the active window in the
attribute set by the wtextattr() function.
Prototype: int winputsf(char *str,char *fmt);
Header: cxlwin.h
Inputs: str - address of the allocated space to receive string
fmt - address of the format string, see section on using
format strings for a complete description.
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - Escape key was pressed
W_INVFORMT - invalid format string
Also see: wgetns wgets winpdef wscanf wsetesc wtextattr
Example:
winputsf(str," !RE! 'Enter phone number: (' ### "
" ') ' ### '-' #### ");
Name: winsline
Purpose: inserts a blank line in active window
Prototoype: int winsline(int wrow,int direc);
Header: cxlwin.h
Inputs: wrow - window row to insert at
direc - scroll direction:
SUP - scroll up
SDOWN - scroll down
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid window row
Also see: wdelline wscroll
Example:
winsline(3,SUP);
Name: wintodisk
Purpose: copies a screen window to a disk file.
Prototype: int wintodisk(int srow,int scol,int erow,int ecol,
char *fname);
Header: cxlwin.h
Inputs: srow - starting row
scol - starting column
erow - ending row
ecol - ending column
fname - address of the string containing file to write to
Return: a zero if no error
Also see: disktowin scrntodisk wsave
Example:
if(wintodisk(10,10,20,20,"WINDOW.DAT")) {
printf("Error creating file\n");
exit(1);
}
Name: wisactiv
Purpose: determines if specified window handle is active.
Prototype: int wisactiv(WINDOW whandle);
Header: cxlwin.h
Inputs: whandle - the handle of the window to check.
65
Return: a zero if handle is not active, a 1 if it is active.
Also see: wactiv wblocked whandle
Example:
printf("handle 5 is %sactive\n",wisactiv(5)?"":"not ");
Name: wmenudef
Purpose: defines a window bar-selection menu option. See the
"Bar-Selection Menu Functions" section for complete details.
Prototype: int wmenudef(int wrow,int wcol,int attr,char *str,
int tagchar,int tagattr,char *desc);
Header: cxlwin.h
Inputs: wrow - window row to display option at
wcol - window column to display option at
attr - attribute to display option with
str - address of the option string
tagchar - tag character to use for identification, may be
an ASCII value (0-255), lower case letters will
automatically be converted to upper case.
tagattr - attribute of tag character
desc - address of a string describing the menu option or
a NULL if no description is to be used. If not
NULL, then the text description of the option will
appear on the next line down and will change with
each menu option, similar to the menus in many
popular spreadsheet packages. The text
description will be displayed in the window's
current text attribute which can be set with the
wtextattr() function. Thus, desc should be NULL
unless using horizontal menus.
Return: W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
Also see: wmenuget
Example:
if(wmenudef(2,3,LCYAN|_BLUE,"Add record",'A',
WHITE|_BLUE,NULL)) {
printf("Error: %s\n",werrmsg());
exit(1);
}
Name: wmenuget
Purpose: gets a window bar-selection menu selection from the
keyboard. See the "Bar-Selection Menu Functions" section
for complete details.
Prototype: int wmenuget(int barattr,int taginit,int pulldown);
Header: cxlwin.h
Inputs: barattr - the attribute to use for the selection bar
taginit - tag character of initial selection bar position.
If an invalid tag character is specified, the
position defaults to the upper left.
pulldown - this specifies how the defined bar-selection
menu will act. It can be one of the following
values:
0 - not part of a pull-down menu
system
66
PDMAIN - main menu of a pull-down menu
system
PDPREV - main menu, automatically select
the previous pull-down menu
PDNEXT - main menu, automatically select
the next pull-down menu
PDMENU - pull-down menu
Return: the tag character of the selected option or zero if an
error. If error, the global variable _werrno will be set to
one of the following:
W_ESCPRESS - Escape key was pressed
If PDMENU is specified for the pulldown parameter, then
wmenuget() will return PDPREV if LeftArrow is pressed,
PDNEXT if the RightArrow is pressed, or PDMENU if Esc is
pressed.
Also see: wmenudef wsetesc wtextattr
Example:
option=wmenuget(LCYAN|_GREEN,'A',0);
switch(option) {
case 'A':
......
case 'D':
......
case 0:
error_routine();
etc.
}
Name: wmessage
Purpose: displays text on the top or bottom border of active window
Prototype: int wmessage(char *str,int border,int leftofs,int attr);
Header: cxlwin.h
Inputs: str - address of message string
border - 0 = top border, 1 = bottom border
leftofs - offset from left border to display message at
attr - attribute of message text
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_STRLONG - string could not fit in window
W_NOBORDER - window has no border
Also see: wtitle
Example:
wmessage("Error!",0,3,LRED|_BLINK);
Name: wmove
Purpose: moves the currently active window to a new location.
Prototype: int wmove(int nsrow,int nscol);
Header: cxlwin.h
Inputs: nsrow - new starting row of window
nscol - new starting column of window
Return: W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
Also see: wcopy wsize
Example:
67
if(wmove(3,10)) {
printf("Error: %s\n",werrmsg());
exit(1);
}
Name: wopen
Purpose: opens a screen window and makes it active, the cursor
location will be initialized to window row 0, column 0, and
the text attribute will be initialized to the same attribute
as the window.
Prototype: WINDOW wopen(int srow,int scol,int erow,int ecol,int btype,
int battr,int wattr);
Header: cxlwin.h
Inputs: srow - starting row
scol - starting column
erow - ending row
ecol - ending column
btype - border box type (0-5). Use btype 5 for a
borderless window.
battr - attribute of window's border.
wattr - attribute of window (and initially the text)
Return: the window handle of the new window or a zero if an error
occurred. If error, the global variable _werrno will be set
to one of the following:
W_ALLOCERR - memory allocation error
W_INVCOORD - invalid coordinates
W_INVBTYPE - invalid box type
Also see: videoinit wactiv wclose wcloseall
Example:
if(!wopen(10,10,20,20,0,LCYAN|_BLUE,LCYAN|_BLUE)) {
printf("Error: %s\n",werrmsg());
exit(1);
}
Name: wperror
Purpose: displays an error message window, waits for a keypress, then
returns to caller.
Prototype: int wperror(char *message);
Header: cxlwin.h
Inputs: message - address of the string containing the error message
Return: W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
W_STRLONG - error message string too long
Also see: werrmsg
Example:
wperror("Input must be numeric");
Name: wpgotoxy
Purpose: sets pseudo cursor coordinates within the currently active
window by wrapping around if coordinates are out of range.
Prototype: int wpgotoxy(int wrow,int wcol);
Header: cxlwin.h
Inputs: wrow - window row (Y coordinate)
68
wcol - window column (X coordinate)
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
Also see: wgotoxy wreadcur
Example:
wpgotoxy(3,20);
Name: wprintc
Purpose: displays a character in the currently active window. Does
not update cursor position. Does not recognize control
characters.
Prototype: int wprintc(int row,int col,int attr,int ch);
Header: cxlwin.h
Inputs: row - cursor row (of the window)
col - cursor column (of the window)
attr - character attribute
ch - character
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
Also see: wprints wputc
Example:
wprintc(5,10,LMAGENTA|BLINK,"T");
Name: wprintf
Purpose: outputs a formatted string to active window at current
cursor position. Works like the standard printf() function
does. Recognizes control characters. Updates cursor
position. Characters will be displayed in the attribute set
by the wtextattr() function.
Prototype: int wprintf(const char *format,...);
Header: cxlwin.h
Inputs: format - format string, refer to the section on printf() in
the run-time library reference.
... - any additional arguments
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wputc wputns wputs wtextattr
Example:
wprintf("%s %c %d\n",string_arg,char_arg,int_arg);
Name: wprints
Purpose: displays a string in the currently active window. Does not
update cursor position. Does not recognize control
characters.
Prototype: int wprints(int row,int col,int attr,char *str);
Header: cxlwin.h
Inputs: row - cursor row (of the window)
col - cursor column (of the window)
attr - attribute
str - address of string
Return: W_NOERROR - no error
W_NOACTIVE - no active window
69
W_INVCOORD - invalid coordinates
W_STRLONG - string too long for window
Also see: wcenters wputs wrjusts
Example:
wprints(5,10,7,"Hello, world");
Name: wputc
Purpose: displays a character in currently active window at current
cursor location. Characters are displayed in the attribute
set by the wtextattr() function. Recognizes control
characters. Updates cursor position.
Prototype: int wputc(int ch);
Header: cxlwin.h
Inputs: ch - the character to be printed
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wdupc wprintc wprintf wtextattr
Example:
wputc('X');
Name: wputns
Purpose: displays a string in the active window, formatting width of
output. Characters are displayed in the attribute set by the
wtextattr() function. Recognizes control characters.
Updates cursor location.
Prototype: int wputns(char *str,int width);
Header: cxlwin.h
Inputs: str - address of the string to print
width - width to display output string with
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wprintf wputs wtextattr
Example:
wputns("Hello, world",5);
Name: wputs
Purpose: displays a string in currently active window at the current
cursor location. Characters are displayed in the attribute
set by the wtextattr() function. Recognizes control
characters. Updates cursor location.
Prototype: int wputs(char *str);
Header: cxlwin.h
Inputs: str - the address of the string to print
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wprintf wprints wputns wtextattr
Example:
wputs("\tHello, world\n\7");
Name: wrestore
Purpose: restores a previously saved window of screen memory.
Prototype: void wrestore(int *wbuf);
Header: cxlwin.h
70
Inputs: wbuf - address of previously saved window
Return: none
Also see: srestore wsave wunhide
Example:
wrestore(wbuf);
Name: wrjusts
Purpose: displays a string right justified to specified column in
active window.
Prototype: int wrjusts(int wrow,int wjcol,int attr,char *str);
Inputs: wrow - window row
wjcol - window column to right justify to
attr - attribute of string text
str - address of string to display
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
W_STRLONG - string too long to fit in window at specified
right justification column.
Also see: wcenters wprints
Example:
wrjusts(3,20,LMAGENTA,"Hello, world");
Name: wsave
Purpose: saves a window of screen memory.
Prototype: int *wsave(int srow,int scol,int erow,int ecol);
Header: cxlwin.h
Inputs: srow - starting row, upper left corner
scol - starting column, upper left corner
erow - ending row, lower right corner
ecol - ending column, lower right corner
Return: address of newly created window buffer or NULL if a memory
allocation error occurred.
Also see: ssave videoinit whide wintodisk wrestore
Example:
int *wbuf;
......
wbuf=wsave(7,7,18,60);
if(!wbuf) {
printf("Memory allocation error\n");
exit(1);
}
Name: wsbounds
Purpose: sets active window's scroll boundaries.
Prototype: int wsbounds(int wssrow,int wsscol,int wserow,int wsecol);
Header: cxlwin.h
Inputs: wssrow - window scroll start row
wsscol - window scroll start column
wserow - window scroll end row
wsecol - window scroll end column
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - invalid coordinates
71
Also see: wscroll
Example:
wsbounds(10,10,20,20);
Name: wscanf
Purpose: inputs a formatted string from keyboard, works like scanf()
does. This function is only supported by Turbo C.
Prototype: int wscanf(const char *format,...);
Header: cxlwin.h
Inputs: format - format string, refer to the section on scanf() in
the run-time library reference.
... - any additional arguments
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wgetc wgetns wgets winpdef winputsf wtextattr
Example:
wscanf("%d %c",&int_value,&char_value);
Name: wscroll
Purpose: scrolls text within the active window, up or down.
Prototype: int wscroll(int count,int direc);
Header: cxlwin.h
Inputs: count - number of lines to scroll
direc - scroll direction:
SUP - scroll up
SDOWN - scroll down
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: wdelline winsline wsbounds
Example:
wscroll(2,SDOWN);
Name: wsetesc
Purpose: sets the Escape checking for window keyboard input functions
that allow Escape checking.
Prototype: void wsetesc(int option);
Header: cxlwin.h
Inputs: option - (0-1), 0 = turn Escape checking off, 1 = turn
Escape checking on
Return: none
Also see: wgetchf wgetns winpread winputsf wmenuget
Example:
wsetesc(0); /* turns Escape checking off */
Name: wsize
Purpose: adjusts the size of the active window.
Prototype: int wsize(int nerow,int necol);
Header: cxlwin.h
Inputs: nerow - new end row of sized window
necol - new end column of sized window
Return: W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
72
W_INVCOORD - invalid coordinates
Also see: wcopy wmove
Example:
if(wsize(23,40)) {
printf("Error: %s\n",werrmsg());
exit(1);
}
Name: wsseldef
Purpose: defines a window string selection record. For a complete
example of using these string selection functions, see the
section "String Selection Functions" in the Tutorial.
Prototype: int wsseldef(char *str);
Header: cxlwin.h
Inputs: str - string to be used for selection
Return: W_NOERROR - no error
W_ALLOCERR - memory allocation error
W_NOACTIVE - no active window
Also see: wsselget
Example:
if(wsseldef("LPT1")) {
printf("%d %s\n",_werrno,werrmsg());
exit(1);
}
Name: wsselget
Purpose: gets a string selection from the keyboard
Prototype: char *wsselget(int attr);
Inputs: attr - attribute of the selections
Return: the address of the selected string or NULL if error. If
error, the global variable _werrno will be set to one of
the following: W_NOERROR - no error
W_NOACTIVE - no active window
W_ESCPRESS - Escape key was pressed
W_NOSELDEF - no selection records defined
Also see: wsetesc wsseldef
Example:
char *p;
p=wsselget(LRED|_GREEN);
if(p==NULL) {
printf("%d %s\n",_werrno,werrmsg());
exit(1);
}
Name: wtextattr
Purpose: sets the default text attribute for text displayed in
active window.
Prototype: int wtextattr(int attr);
Header: cxlwin.h
Inputs: attr - the new text attribute
Return: W_NOERROR - no error
W_NOACTIVE - no active window
Also see: attrib wchgattr
Example:
73
wtextattr(LMAGENTA|BLINK);
Name: wtitle
Purpose: gives active window a title and displays title on top border
line of window.
Prototype: int wtitle(char *str,int tpos,int tattr);
Header: cxlwin.h
Inputs: str - address of title string or NULL to delete title
tpos - position of title:
TDELETE - to delete title
TLEFT - left justified
TCENTER - centered
TRIGHT - right justified
tattr - attribute of window's title
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_STRLONG - title string too long for window
W_INVTPOS - invalid title position argument
Also see: wmessage
Example:
wtitle("[ My Window ]",TCENTER,YELLOW);
Name: wunhide
Purpose: unhides a previously hidden window.
Prototype: int *wunhide(int **wbuf);
Header: cxlwin.h
Inputs: wbuf - address of the pointer to the window buffer to
unhide
Return: the address of the unhidden window's buffer or a NULL if a
memory allocation error occurred
Also see: whide wrestore
Example:
if(!wunhide(wbuf)) {
printf("Memory allocation error\n");
exit(1);
}
Name: wvline
Purpose: draws a vertical text line in active window using characters
defined by given box type. If vertical line crosses a
horizontal line of the same box type, an appropriate
intersection or corner will be used.
Prototype: int wvline(int wsrow,int wscol,int count,int btype);
Header: cxlwin.h
Inputs: wsrow - window start row of line
wscol - window start column of line
count - number of line characters to display
btype - box type (0-5)
Return: W_NOERROR - no error
W_NOACTIVE - no active window
W_INVCOORD - entire text line could not fit in window
W_INVBTYPE - invalid box type
Also see: whline wtextattr
Example:
74
wvline(3,9,14,1);
75
